A postmortem is the document that turns an incident into an improvement. Done well, it is one of the highest-value pieces of writing an organisation produces: a permanent, specific record of how a system actually behaved under stress. Done badly, it is a document nobody reads, written to satisfy a process, ending in three action items that are never completed and one implied conclusion about whose fault it was.
What "blameless" actually means
It does not mean pretending nobody did anything. It means starting from the premise that people act reasonably given the information, tools and pressure available at the time — and that if someone made a decision that turned out to be wrong, the interesting question is why it looked right.
The practical test: an engineer who caused an outage should be able to write the postmortem themselves, honestly, without professional risk. If that is not true in your organisation, your postmortems will be incomplete, because the people who know most about what happened have a reason to say less.
Blamelessness is not niceness. A blameless postmortem can be uncomfortable — it can conclude that a review process is theatre, that alerting was ignored for months because it was noisy, or that a deadline pushed a change out untested. Those conclusions are about systems, and they are the useful ones.
Why it works: in a culture that assigns blame, engineers hide details, avoid documenting, and route around review. The organisation gets a comfortable narrative and learns nothing. The purpose here is accurate information about failure, and that requires making honesty free.
The structure
Title and metadata. A descriptive title — "Checkout unavailable for 47 minutes after config deploy" — plus date, duration, severity, and authors. Titles matter because people search for these later.
Summary. Three or four sentences: what broke, who was affected, how long, what fixed it. Written so that someone with no context understands the shape of the event.
Impact. Concrete and quantified: how many users, which functions, what they experienced, revenue or SLA consequence, whether data was lost. Vague impact statements make the whole document harder to weigh against others.
Timeline. The core of the document. Timestamped, from the change or condition that set it up through detection, diagnosis, mitigation and resolution. Include what people believed at each point, not only what was true — "14:22 — team believed the issue was upstream because the dashboard showed the API as healthy; the dashboard was stale" is far more informative than "14:22 — investigated API".
Detection. How did you find out? Alert, customer report, someone noticing? Time to detect is often the biggest lever available and the most consistently neglected.
Root causes. Plural. Real incidents have several contributing conditions, and the single-cause framing is almost always a simplification chosen for tidiness.
What went well. Genuinely, not as a courtesy. Fast rollback, a runbook that worked, a good escalation decision — these deserve recording because they are the practices worth reinforcing.
Action items. Specific, owned, dated, tracked in the same system as other work.
Supporting material. Graphs, log excerpts, links to the change, the incident channel transcript.
Finding causes without landing on a person
The technique that keeps analysis moving past the first plausible answer is to keep asking why, but the discipline is to ask it about the system:
- The deploy took down checkout. Why?
- A config change removed a required field. Why did that reach production?
- The change passed review. Why did review not catch it?
- The reviewer could not see the effect from the diff. Why not?
- The config format gives no indication which fields are required. Why does nothing validate it?
- There is no schema for this config. — an actionable finding.
Note where this landed: not on the reviewer. "The reviewer should have been more careful" is not a finding, because it is not actionable and it will not be true of the next reviewer either. "Config has no schema validation" is a finding you can fix once, permanently.
Two useful principles. Counterfactual reasoning is a trap: "if only they had checked X" describes a world you cannot build, since you cannot make people not miss things. And hindsight bias is constant: the cause is obvious once you know it, and was not obvious to people looking at partial information under time pressure. Ask what information they had, not what they should have concluded.
Action items that get done
Most postmortem action items expire quietly. What separates the ones that do not:
- Specific. "Improve monitoring" is not an action item. "Add an alert on checkout error rate above 1% over 5 minutes" is.
- Owned by a person, not a team. Team ownership is nobody's ownership.
- Dated, with a real date.
- Tracked in the normal work system, prioritised against everything else. Action items in a document nobody opens again do not exist.
- Sized to be done. Three completed items beat eleven that are open a year later.
- Categorised by whether they prevent recurrence, reduce impact, or improve detection. A postmortem whose actions are all prevention has neglected the fact that the next failure will be a different one — detection and mitigation improvements pay off across incidents.
Follow-through is what makes the practice worth anything. An organisation that writes excellent postmortems and completes none of the actions has an expensive documentation habit.
Related: tracking action items after meetings and task management best practices.
Running the review
- Write the draft within a day or two, while memory is fresh and the incident channel is still readable. Precision decays fast.
- The person closest to the incident writes it, with support. Handing it to someone uninvolved produces a document without the detail that matters.
- Circulate the draft before the meeting. The meeting is for discussion, not for reading aloud.
- Timebox the review. An hour, focused on causes and actions rather than re-narrating the timeline.
- Invite people who were not involved. They ask the questions insiders have stopped seeing, and they learn from the incident without having lived it.
- Watch the language in the room. "Why did you deploy at 5pm" and "what made deploying at 5pm seem reasonable" produce different meetings.
The meeting-craft ground is in running a productive retrospective and meeting agendas that earn the meeting.
Making them useful later
A postmortem's second life is as a searchable record, and most organisations get no value from this because the documents are scattered.
- One location, indexed, searchable, permanently retained.
- Consistent titles and tags — affected service, cause category, severity.
- Readable by anyone in the organisation. Restricted postmortems teach nobody.
- Reviewed in aggregate, quarterly. The pattern across twenty incidents is more valuable than any single document, and it is invisible unless someone looks. Three outages from the same class of configuration error is a finding no individual postmortem could produce.
This is the same argument as building a team knowledge base and writing a decision log: the value is in the accumulated record, which requires the individual documents to be findable.
Beyond software
The practice generalises. Any organisation that has failures worth understanding — a missed deadline, a lost client, a compliance breach, a botched launch — benefits from the same document and the same discipline. The obstacles are cultural rather than technical: it requires a genuine willingness to record that the process failed rather than that a person did.
Summary
Write it within days, by the people closest to it, with a timestamped timeline that records what people believed as well as what was true. Find multiple contributing causes and keep asking why until the answer is a system property rather than a person's attention. State the impact concretely, record what went well, and produce a small number of specific, owned, dated actions tracked with real work. Then keep the document somewhere searchable and read the set of them quarterly — the pattern across incidents is where most of the value actually is.
