Postmortem Best Practices: Writing One People Actually Read

Most postmortems are archaeology: an accurate record of something nobody will change. A useful one produces a small number of things that actually get done.

The purpose of a postmortem is not to document what happened. It is to make the next incident less likely or less damaging. Everything in the document should serve that, and anything that does not is ceremony.

Blameless is a mechanism, not a manner

Blameless postmortems are often explained as being kind. That undersells them. They exist because people who expect blame withhold information — and the withheld information is precisely what would have prevented recurrence.

Structure that works

1. Summary — three sentences: what broke, for how long, who was affected. Most readers stop here, so it must stand alone.
2. Impact — duration, users affected, revenue or data consequences, in numbers where possible
3. Timeline — facts with timestamps, from first symptom to resolution, including when humans became aware
4. Contributing factors — plural, and honest about the process ones, not just the technical trigger
5. What went well — genuinely useful for reinforcing the detection or response that worked
6. Action items — each with an owner and a date

Root cause is usually a story, not a line

"The deploy caused the outage" is where analysis stops when the meeting is rushed. Real contributing factors usually look like this:

Four of those five are process problems. Fix only the trigger and the same class of incident returns wearing different clothes.

Action items: the part that decides whether any of this mattered

• Three to five items maximum — a list of twenty is a list of zero
• Each with a named owner, not a team
• Each with a date, tracked in the same system as normal work
• Prefer items that remove a class of failure (a guardrail) over items that fix one instance
• Review them at the next postmortem — unfinished items from last time are the most important agenda item

A postmortem with no completed action items by the next incident is not a process. It is a filing habit.

Timing and audience

• Draft within 48 hours — accuracy decays fast
• Meet for 30-45 minutes, not longer; the document does most of the work
• Include everyone who was involved, plus one person who was not (they ask the obvious questions insiders skip)
• Share it widely — internal transparency about failure is how organisations get better at it

Make prevention work independently verifiable

A postmortem is useful when it changes a control or decision. Assign evidence of completion to each action, not just a due date.

1. Separate observed facts, hypotheses and contributing conditions.
2. Link every action to the failure mechanism it addresses.
3. Verify the change with a test, alert exercise or restore drill.

• how to handle a production outage →
• devops consulting services →