What Do I Write in an Automation Post-Mortem?

What should go into a post-mortem when an automation breaks?

A useful automation post-mortem answers five questions in plain words: what happened, who and what was affected, why it happened, how it was fixed, and what changes so it does not happen again. I keep mine to one page, write it within a day or two, and never use it to assign blame.

Every automation breaks eventually. An API changes, a field gets renamed, a rate limit kicks in, or a perfectly reasonable edit in one tool quietly breaks a workflow in another. The failure itself is rarely the real cost. The real cost is when the same failure happens again because nobody wrote down what was learned.

I run automations in production for clients like Ajust, where Airtable and WhaleSync power the workflow behind 25,000+ cases delivered, and Kismet Health, where HubSpot runs through Zapier. When people depend on a system, a short written record after something goes wrong is part of the job. Here is the structure I use and why each part is there.

Why write a post-mortem for a small automation at all?

Because small automations often touch important things: leads, customer records, invoices, or messages to real people. A post-mortem turns a stressful incident into a permanent improvement. Without one, the fix lives only in someone's memory, and memory is a poor monitoring system. One page now saves hours later.

There is a common belief that post-mortems are for engineering teams with big outages. I disagree. A Zap that silently stopped creating deals for three days can hurt a small business more than a short site outage hurts a large one.

Writing it down also changes how I think about the system. When I have to explain the cause in plain words, I often notice that the real problem was not the broken step. It was the missing alert, the unclear ownership, or the assumption nobody tested.

And it builds trust. Clients do not expect automations to be perfect. They do expect honesty about what went wrong and a clear plan to make it less likely next time.

How do I describe what happened?

I start with a short timeline in plain sentences: when the problem began, when it was noticed, who noticed it, when it was fixed, and when everything was confirmed back to normal. Times matter more than adjectives. The gap between when it started and when someone noticed is often the most important number in the whole document.

I write the summary so that someone who was not involved can understand it in thirty seconds. That usually means one short paragraph before any detail. If the client's operations lead can read it and explain it to their manager, it is clear enough.

Then I add the detail: which workflow, which step, which platform, and what the error looked like. I link to the run history or logs where possible, so the evidence is one click away.

I avoid dramatic language. Words like catastrophic or disaster make people defensive and make the document harder to learn from. A calm, factual tone keeps the focus on the system.

How do I measure the impact honestly?

I state exactly what was affected: how many records, which people, which processes, and for how long. If I do not know an exact number yet, I say so and give the method I will use to find out. Underplaying impact destroys trust. Overstating it causes panic. Accuracy is the only safe choice.

Impact is not only about volume. Ten wrong records might matter more than a thousand delayed ones if those ten were messages sent to the wrong people. I describe the human effect as well as the count.

I also record whether any data needs repair. If records were missed or written incorrectly, the post-mortem points to the cleanup plan. My guide on backfilling data after an automation outage covers how I approach that part.

How do I find the real cause, not just the trigger?

I separate the trigger from the cause. The trigger is the event that set things off, like a renamed field. The cause is why the system could not handle it, like no validation step and no alert. I keep asking why until I reach something I can actually change in the design, not just in the data.

Stopping at the trigger is the most common mistake. If the post-mortem says the failure happened because someone renamed a field, the implied fix is telling people not to rename fields. That will not hold. The better question is why a renamed field could break a workflow silently for days.

Most of the causes I find fall into a few groups: no alert when a step fails, no owner for the workflow, an untested assumption about input data, or two systems writing to the same field. Naming the group helps me see patterns across incidents.

I also note what went right. If an alert fired quickly or a backup made recovery easy, I write that down too. It tells me which protections are worth repeating.

What goes into the fix section?

I separate the immediate fix from the lasting fix. The immediate fix is what restored service, such as remapping a field or rerunning failed tasks. The lasting fix is the change that makes the same failure less likely or easier to catch, such as a new alert, a validation step, or a clearer owner.

Immediate fixes are usually quick and obvious. Lasting fixes take more thought and are easy to skip once the pressure is off. That is exactly why they need to be written down with a named owner and a date.

If a rollback was involved, I describe what was rolled back and whether it worked as planned. I wrote about planning those in advance in a rollback plan for an automation that went wrong, and every post-mortem is a test of whether that plan held up.

I keep the list of lasting fixes short. Two or three changes that actually ship are worth more than ten good ideas that never do.

How do I keep a post-mortem blameless?

I write about systems and decisions, not people. Instead of saying who made a mistake, I describe what the system allowed to happen. If a person's action triggered the failure, I ask what would have made the safe action easier or the risky one harder. People share more when they are not afraid of being blamed.

Blameless does not mean vague. The timeline still says what happened and in what order. It just avoids turning a sequence of events into a verdict about someone's competence.

This matters most with clients. If an operations person changed a form field and broke a workflow, the honest lesson is that the workflow should have been protected or monitored. Blaming them teaches the whole team to hide problems, which is the worst possible outcome for anyone running automations.

The same rule applies to me. When the cause was something I built or missed, I say so plainly. Owning my part is what earns the right to ask others to change theirs.

What happens after the post-mortem is written?

I share it with everyone affected, agree on owners and dates for each lasting fix, and add a short note to the automation's entry in the inventory. Then I check back on the agreed date. A post-mortem that is written and never revisited is a diary entry, not an improvement.

Sharing it quickly matters. A short, honest note within a day or two calms people down far more than silence followed by a long report.

The follow-up is where most teams fall short. I put the lasting fixes on a calendar, not just in the document. When the date arrives, either the fix is done or the client and I decide together whether it still matters.

Over time, the collection of post-mortems becomes a useful record. Patterns show up. If several incidents trace back to missing alerts, that tells me where to invest before the next one.

How do post-mortems change the way I build new automations?

They shape my pre-flight checks. Each lesson from a post-mortem becomes a question I ask before the next automation goes live: does every failure alert a person, does every workflow have an owner, and does every write to an important field have a guard. The post-mortem closes the loop back to design.

That is the real return. A single post-mortem fixes one workflow. A habit of post-mortems improves every workflow that comes after it.

I described my pre-launch checklist in why I run a pre-flight check before an automation goes live. Much of what is on that list exists because something, somewhere, went wrong once and someone took the time to write it down.

What should you do next?

Take the last automation failure your team had, even a small one, and write a one-page post-mortem using five headings: what happened, impact, cause, fix, and lasting changes. Keep it blameless, give each lasting change an owner and a date, and share it with everyone affected.

You will probably find the cause was not what everyone assumed. That discovery alone is worth the hour.

If you want help building automations that fail loudly and recover cleanly, or reviewing ones that have already broken, reach out at pravinkumar.co. Let's chat.