Most automations that fail were never defined. Nothing was wrong with the tooling — nobody wrote down what "working" meant, so it could never be reached or recognised.
Fill this in before you build. If you cannot fill a section, that is the part you have not decided yet.
1. The workflow, in one sentence
When [trigger], we currently [manual steps], which takes [time] and fails when [failure mode].
One sentence. If it takes two, you have two automations.
2. What it must produce
The output, named concretely. Not "better visibility" — "a row in the sheet with these seven fields, within ten seconds of submission."
Output:
Where it lands:
Who uses it:
3. Definition of done
Three tests, written before the build:
- Happy path: given [input], [output] appears in [place] within [time].
- Failure path: if [integration] is unavailable, [specific alarm] reaches [specific person] within [time].
- Duplicate path: if the same input arrives twice, [exact behaviour].
Test 3 is the one people skip. It is also the one that produces the mess six months later.
4. What it must never do
The guardrails, stated as prohibitions:
- Must never send email to an address it was not given
- Must never modify or delete records it did not create
- Must never run without logging what it did
Write your own. Every prohibition here is a future incident that does not happen.
5. Who is told when it breaks
An automation that fails silently is worse than the manual process, because the manual process at least had a person looking at it.
Alarm goes to:
Channel:
Silence is acceptable for: (e.g. quiet periods with no traffic)
6. What it replaces, and what stays manual
The honest boundary. Anything not listed here will quietly become the automation's problem.
Automated:
Still manual, on purpose:
Because:
7. Cost of being wrong
If this runs incorrectly for a week before anyone notices, what is the damage? Money, client trust, compliance exposure, or nothing much?
The answer decides how much testing and monitoring is proportionate. A newsletter archive can fail silently. A payment run cannot.
---
Keep the filled brief with the build. When someone asks in six months why it works this way, the brief is the answer.