How to Write a Postmortem

Not every hiccup needs a full write-up. The SRE book recommends defining the triggers before an incident happens, so nobody has to argue about it afterward. Its examples include:

• User-visible downtime or degradation beyond a set threshold.
• Data loss of any kind.
• An on-call engineer having to intervene, such as rolling back a release or rerouting traffic.
• Resolution time above a set threshold.
• A monitoring failure, which usually means a person discovered the incident instead of an alert.

It adds that any stakeholder may request a postmortem for an event.

The depth of the analysis should match the stakes. The PubMed Central review notes that a single full root cause analysis can take 20 to 90 person-hours (as reported in that review, read on 2026-10-17), which is why lighter methods exist for less harmful events. It describes brief after-action reviews and team debriefs as options for smaller incidents, and argues that the level of harm and the likely frequency of the risk should decide how deep the investigation goes.

The SRE book calls blameless postmortems a tenet of its culture. A blameless postmortem focuses on the contributing causes without indicting any person or team for bad behavior, and it assumes everyone involved had good intentions and did the right thing with the information they had. The reason is practical: if people are shamed for mistakes, they stop bringing issues to light. As the chapter puts it, you can't fix people, but you can fix systems and processes to better support people making the right choices.

PagerDuty's postmortem guide draws on Sidney Dekker's distinction between two views of human error. The old view says people's mistakes cause failure, so removing the "bad apples" prevents it. The new view treats human error as a symptom of a deeper problem in the system. Only the new view produces learning.

PagerDuty also argues that perfect blamelessness is unrealistic, because the urge to blame is deeply human, and recommends being "blame aware" instead. It names the biases to watch for:

The words you use matter. PagerDuty recommends asking "what" and "how" questions, such as "What did you think was happening?" and "What did you do next?", and avoiding "why did you" questions, which force people to justify themselves. It also suggests asking why a reasonable, rational and decent person might have taken the action that seems to have caused the incident.

Atlassian addresses the common objection that blamelessness removes accountability. Its answer is that removing the fear of reprisal is exactly what makes people honest about their missteps, and honesty is the only route to fixing them. It gives an example from its own history: an engineer's configuration syntax error took the company down for 45 minutes, and the blameless review led to an automated check that now prevents that class of mistake entirely. The engineer stayed.

Before anyone analyzes causes, agree on what happened. Atlassian calls the timeline the step that stops a postmortem from going off the rails, because a misunderstanding of the core facts derails everything after it.

incident.io recommends assigning a single postmortem owner as soon as the incident is resolved, ideally the person who led the response, and starting timeline reconstruction within 24 hours while chat threads and memories are still fresh. The longer you wait, it warns, the more narrative replaces evidence.

A good timeline:

• Uses timestamps from logs, alerts, chat and tickets, all in one time zone.
• Starts before the incident, at the change or condition that set it up, which PagerDuty recommends as a defense against hindsight bias.
• Records what people knew and believed at each moment, not just what they did.
• Marks detection, escalation, mitigation and resolution clearly.
• Notes what went well in the response, not only what went wrong.

incident.io also advises never opening the review meeting with a blank document. The owner drafts the timeline, impact and a first pass at contributing factors, and the meeting's job is to challenge and deepen that draft.

With the facts agreed, ask why. Two common techniques are the five whys and the fishbone diagram. Retrium's guide to root cause analysis describes the five whys as asking "why" repeatedly, usually five times, to move from the symptom toward its cause, and the fishbone diagram as a way to group possible causes into categories so a team can see them together. Retrium recommends starting a fishbone with a clear, agreed problem statement.

Use these tools to find several causes, not one. incident.io notes that modern reliability practice prefers "contributing factors" over a single "root cause", because failures in complex systems arise from multiple interacting conditions. It suggests listing two to five systemic factors explicitly, framed in terms of process gaps, tool limitations or documentation failures rather than people.

A practical way to frame each factor is as a condition that allowed the incident, not an action someone took:

The second column produces fixes you can build. The first produces "be more careful", which is not a fix.

This is where most postmortems fail. The SRE workbook's chapter on postmortem practices contrasts a bad postmortem with a good one, and the action items are the clearest difference. In the bad example, action items used vague words like "improve" and "make better", were mostly mitigative with one item that amounted to "make humans less error-prone", all had the same priority and mostly had no owner or tracking ticket. The workbook notes that trying to change human behavior is less reliable than changing automated systems and processes.

In the good example, every action item has an owner and a tracking number, a priority, and a verifiable end state such as "add an alert when more than a set percentage of machines are taken away". Items are grouped by theme and include both prevention and mitigation.

A checklist for each action item:

1. Specific verb and object. "Add a confirmation prompt to the production deploy command", not "improve deploys".
2. One owner. The workbook notes that action items without clear owners are less likely to be resolved, and favors a single owner with collaborators.
3. Priority. So the team knows what to do first.
4. Due date and tracking ticket. In the same tracker as other work, not only in the document.
5. Verifiable end state. Anyone can check whether it is done.
6. Type. Prevent (stops this class of failure), mitigate (reduces impact next time) or detect (finds it faster).

incident.io offers a blunt test. "We should improve our deployment pipeline" is not an action item. A named person adding a specific check to a specific step by a specific date is. It also warns that when fewer than half of postmortem action items get completed, the postmortems are theater (as stated by incident.io, read on 2026-10-17).

Here is a compact template that covers everything above:

TITLE:                    DATE:            SEVERITY:
OWNER:                    STATUS: draft / in review / final

SUMMARY: two or three sentences a non-specialist can follow
IMPACT: who was affected, how, for how long, and the cost if known
TIMELINE: timestamped events from the triggering change to resolution
DETECTION: how we found out, and how we could have found out sooner
CONTRIBUTING FACTORS: two to five systemic conditions
WHAT WENT WELL:
WHERE WE GOT LUCKY:
ACTION ITEMS:
  | Action | Type | Owner | Priority | Ticket | Due |
LESSONS: what someone joining next year should know

The SRE book states it plainly: an unreviewed postmortem might as well never have existed. It suggests having experienced reviewers check that key data was captured, the impact assessment is complete, the causes go deep enough, the action plan is appropriate and the outcome was shared with the right people. Atlassian recommends naming who approves the action items, which in its case is a division-level engineering leader.

Then share it as widely as is useful. The SRE book describes sharing postmortems with the wider organization and keeping them in a searchable repository. It also lists ways to build the habit: a "postmortem of the month" in a newsletter, reading clubs where teams discuss an interesting past incident, and visibly rewarding people for doing the right thing. Its example is an engineer whose quick rollback limited an outage to four minutes and who was publicly praised for it.

The SRE workbook adds one more incentive worth copying: reward people for closing action items, not only for writing postmortems. Otherwise, it warns, teams produce a stream of documents with unfinished plans.

Finally, review the process itself every few months. Are action items closing? Are the same contributing factors appearing in several incidents? A pattern across postmortems is often more valuable than any single one. Teams that use Quanta Intelligence agents to draft first-pass timelines from chat logs still keep the analysis and the action items with people, because that is where the learning happens.