A well-written postmortem turns an incident into lasting organizational learning — preventing recurrence and improving response for next time. This guide covers structuring one effectively.
The Core Principle: Blameless
An effective postmortem focuses on systems and processes, not individual blame — people generally act reasonably given the information and tools available to them at the time; the goal is understanding and improving the system that allowed the incident to happen, not assigning fault.
When to Write a Postmortem
Any incident with meaningful customer impact, significant internal disruption, or genuine learning value warrants a postmortem — not every minor blip needs one, but err toward writing one when uncertain, since the learning value usually outweighs the time cost.
Standard Postmortem Structure
1. Summary
A brief, 2-3 sentence overview: what happened, impact, and duration — readable by someone who wants the gist without reading the full document.
2. Impact
Quantify the actual impact: how many users affected, revenue impact if applicable, duration of the issue.
3. Timeline
A detailed, timestamped sequence of events — when the issue started, when it was detected, key investigation steps, and when it was resolved. Be specific and factual, avoiding speculation in the timeline itself.
4. Root Cause
What actually caused the issue — go beyond the surface symptom to the underlying cause; "the server ran out of disk space" is a symptom, "log rotation wasn't configured for a new high-volume log source" is closer to root cause.
5. Detection
How was the issue discovered — automated alert, customer report, manual observation? This reveals gaps in monitoring coverage if detection was slower or less automatic than it should have been.
6. Resolution
What specific actions resolved the issue.
7. What Went Well
Genuinely useful to include — effective response actions worth reinforcing and repeating in future incidents.
8. What Went Poorly / Contributing Factors
Honest assessment of what made the incident worse or harder to resolve than it needed to be — slow detection, unclear runbooks, missing access, and similar factors.
9. Action Items
Specific, assigned, and tracked follow-up tasks to prevent recurrence or improve future response — a postmortem without concrete action items risks becoming a purely retrospective exercise with no lasting improvement.
Writing Action Items Effectively
[ ] Add disk space alerting at 80% threshold (Owner: Jane, Due: [date])
[ ] Document log rotation setup in the server provisioning runbook (Owner: Sam, Due: [date])Each action item needs a clear owner and target date — vague items like "improve monitoring" without ownership rarely get completed.
Sharing the Postmortem
Share broadly within the team/organization (respecting any genuinely sensitive details) — the learning value multiplies when more people internalize what happened and why, not just those directly involved in the incident.
Following Up on Action Items
Track postmortem action items to actual completion, not just creation — an unfinished action item list undermines the entire purpose of the exercise. See How to Run an Incident Response Retrospective (Blameless Postmortems) for the broader review process this fits into.
Common Errors
Postmortem focuses on blaming a specific person — immediately undermines psychological safety and discourages honest reporting of future incidents; redirect focus to systemic factors.
Continue Reading
- How to Run an Incident Response Retrospective (Blameless Postmortems)
- How to Set Up an On-Call Rotation and Alerting Escalation Policy
- How to Build a Status Page for Your Service
Browse more articles in Advanced Observability & Incident Management.
