The Automation Runbook: What to Write Before You Ship

Why does an automation that worked on day one quietly break in week six?

Because nobody wrote down what working looked like. The automation did not decay. A field got renamed, an API changed shape, someone added a required property in the CRM, and there was no record of the assumptions the workflow was built on, so nothing caught it and nobody noticed until a customer did.

This is the single most expensive pattern I see in small automation stacks. The build takes an afternoon. The silent failure costs weeks of bad data, and it is almost always discovered by accident.

The fix is not more monitoring software. It is a page of writing you produce before you turn the thing on. I call it a runbook, and here is what goes in it.

What is an automation runbook, and why write it before you ship?

A runbook is a short document that says what an automation does, what it assumes, how it fails, who finds out, and how to turn it off. Write it before you ship because the moment of building is the only time you actually hold all of that in your head. A week later you will not.

Most people write documentation as an afterthought, which is why most documentation is a description of the happy path. A runbook is not a description. It is a set of commitments about behavior that you can check against reality later, and that someone who is not you can act on at nine on a Friday evening.

Keep it to one page. If it takes longer than twenty minutes to write, the automation is probably doing too many things and should be split. That constraint is doing real work: an automation you cannot describe on one page is an automation you cannot debug quickly either.

What belongs in the trigger and scope section?

Three things. What starts this, what it is allowed to touch, and what it must never touch. Write the third one explicitly, because the absence of a stated boundary is how a lead-enrichment job ends up overwriting a sales rep's manual notes.

The trigger line should name the exact event and the exact source. Not a new form submission, but a submission to the specific form on the specific page, in the specific tool. When a workflow misfires, the first question is always whether it fired on something it should have ignored, and a vague trigger description makes that question unanswerable.

For scope, list the records and fields the automation writes to, whether that is HubSpot, Airtable, Notion, Google Sheets or a Webflow CMS collection. This is the section that turns into a review checklist later, and it is the one that saves you when someone asks whether the automation could possibly have caused a data problem in a field you have never thought about.

I learned this one the hard way rather than from a book, and I wrote more about the specific shape of the damage in my piece on stopping an automation from sending bad data into your CRM.

How do you write down what failure actually looks like?

List the ways this can go wrong, in plain language, before it does. Not exception types. Things like: the source field is empty, the record already exists, the API is down, the model returns something that is not valid JSON, a human edited the record mid-run. Each line gets a decision: retry, skip, stop, or escalate.

This is the part people skip, and it is the part that pays for the whole exercise. The difference between an automation that degrades gracefully and one that corrupts a database is almost never technical sophistication. It is whether somebody sat down and thought about the empty field for thirty seconds.

The useful distinction to make explicit is between a failure that should stop everything and a failure that should be skipped and logged. A missing phone number on one lead should not halt a pipeline. A missing email on every lead should, because that pattern means something upstream is broken and continuing just multiplies the mess.

Write the difference down. Under pressure, nobody reasons about this well, and a line in a runbook that says stop the run and page me is worth more than a clever retry loop.

What do the tools give you for free, and what do you have to build yourself?

Less than you would hope, and it varies by platform, so check rather than assume. Zapier's documentation states that Autoreplay is available on the Professional, Team and Enterprise plans, and that it will not replay safely halted Zap runs. So on a Free plan, retries are your problem, and even with Autoreplay on, a halted run still needs a human.

n8n takes a different approach. Its documentation describes an error workflow as a separate workflow that runs when an execution fails, says that the error workflow must start with the Error Trigger node, and has you select it in the main workflow's settings. That is a genuinely good pattern, because it means your alerting logic lives in one place instead of being copied into every workflow you own.

The n8n docs also flag a limitation worth knowing before you rely on it: if the error happens in the trigger node itself, the execution ID and URL are absent, because the workflow never fully executed. That is exactly the failure you most want to catch, and it is the one that arrives with the least information attached.

Pricing, plan gating and retry behavior all move, so treat this section of your runbook as something to re-check against the vendor's own docs rather than something you write once. I compared the broad shape of these platforms in my notes on choosing between Make, Zapier and n8n, but the specific limits are always a docs question.

Who gets told when it breaks, and how fast?

Name a person, not a channel. A Slack channel that everyone can see is a channel nobody owns, and an alert with no owner is a notification that gets muted within a fortnight. Write down one name, and a second name for when the first is unavailable.

Then set the threshold honestly. An alert on every single error trains people to ignore alerts. An alert on a pattern, such as three failures in an hour or any failure at all in a workflow that runs once a week, tells you something. The right threshold depends entirely on how often the thing runs, which is why it belongs in the runbook for that specific automation and not in a global policy.

The other half of this is a heartbeat. An automation that fails loudly is easy. An automation that stops running altogether is the dangerous one, because silence looks exactly like success. If a workflow should fire at least once a day, something needs to notice when it does not.

What does a rollback plan look like for an automation?

It answers two questions: how do I stop it right now, and how do I undo what it already did. The first is usually a switch. The second is usually much harder, and that difficulty is the reason to think about it in advance rather than during an incident.

The practical move is to make your writes reversible by design. Stamp every record the automation creates or modifies with a marker: the automation name and a timestamp. It costs one field. It means that when something goes wrong you can find exactly what this workflow touched, instead of guessing from timestamps and hoping.

For the automations I run in production this is not optional. For Ajust I run an Airtable and WhaleSync setup that has helped deliver more than 25,000 cases, helped over 400,000 people, and saved more than 50,000 hours. At that volume, an unmarked bad write is not an inconvenience, it is an archaeology project. For Kismet Health I run HubSpot automation through Zapier, and the same rule holds.

Also write down what should never be rolled back automatically. Anything that has already sent an email to a customer cannot be undone, and pretending otherwise in a runbook is worse than admitting it.

How do you keep a runbook from going stale?

Attach it to the thing it describes and review it on a fixed date. A runbook in a folder nobody opens is not documentation, it is a memento. Link it from the workflow itself, in the description field, so the next person to open the automation finds it without being told it exists.

The review cadence I use is simple: whenever I change the automation, and once a quarter regardless. The quarterly pass is not about the automation, it is about the world around it. Plans change, APIs deprecate endpoints, a client restructures their CRM. The runbook is where those assumptions were written down, so it is the right place to check them.

Across 70 plus projects for 25 plus clients over the last 6 plus years, the automations that survived were not the clever ones. They were the ones where somebody could still explain, a year later, what the thing assumed. That is the entire value of the exercise.

There is a related decision that a runbook forces you to confront, which is where a human should sit in the loop at all. I worked through that separately in when to keep a human in the loop.

What should you do next?

Pick the automation you would be most upset to discover had been broken for a month, and write its runbook this week. One page. Trigger and scope, failure modes with a decision on each, what the platform handles versus what you handle, who gets told, how to stop it, how to undo it, and when you will read this again.

Then do the uncomfortable part: check whether the automation currently behaves the way the page you just wrote says it does. In my experience it often does not, and the gap you find is the most valuable output of the whole exercise.

I build and maintain automations like this for founders and marketing teams, on fixed fees, with most projects landing between 1,000 and 10,000 dollars. If you have a workflow running in production that nobody has documented and everyone depends on, reach out and let's chat.