Writing Postmortems
Turns an incident into a blameless postmortem with a timeline, contributing factors and owned action items, using language that describes systems rather than assigning fault. Use after an outage, a data loss event, a failed deploy, or when the user asks for an incident report or RCA.
- Skill name
writing-postmortems- Category
- devops
- Price
- Free
- Install
~/.claude/skills/writing-postmortems/SKILL.md- Tags
- incident, postmortem, rca, reliability, sre
Writing Postmortems
A postmortem is read by people who were not there, months later, deciding whether a change is safe. Write for them.
Structure
# <Service>: <what users experienced> — <date>
**Impact.** Who was affected, how many, for how long, and what they could not do.
**Detection.** How it was noticed, and how long that took.
**Resolution.** What ended the impact.
## Timeline
All times UTC.
| Time | Event |
| --- | --- |
| 09:14 | Deploy of build 4821 begins |
| 09:22 | Error rate on /checkout passes 5%, no alert fires |
| 09:41 | Customer support reports failed payments |
| 09:44 | Incident declared |
| 10:02 | Build 4820 rolled back; error rate returns to baseline |
## What happened
Two or three paragraphs of mechanism. What broke, why that broke it, and why
the safeguards did not stop it.
## Contributing factors
1. …
2. …
## What went well
…
## Action items
| Action | Owner | Due | Ticket |
| --- | --- | --- | --- |Impact is measured, not adjectival
"Significant impact" tells a reader nothing. "Checkout failed for 4% of sessions for 48 minutes; 1,180 orders affected; all recovered on retry" tells them the size, the shape and the cost. If the number is unknown, say it is unknown and say who is finding it.
Blameless means describing the system
Blameless does not mean vague. It means the failure is described in terms of conditions rather than character, because the same conditions will produce the same outcome with a different person in the chair.
| Instead of | Write |
|---|---|
| The engineer forgot to run the migration | The deploy pipeline had no step that verified pending migrations, so a build could reach production ahead of its schema |
| Human error | The console offered no confirmation before dropping an index on a production database |
| Bad judgement under pressure | The runbook offered two remedies with no criterion for choosing, during an active outage |
Keep names out of the narrative. Use roles.
Contributing factors, not one root cause
Systems that fail from a single cause are rare; the safeguards each failed for their own reason. List each factor, and mark which of them was necessary:
- The alert threshold was set at 10% error rate; the incident peaked at 6%
- The canary stage runs for 60 seconds; this failure surfaces after ~4 minutes
- Rollback was manual, and the runbook link in the alert was stale
Action items that survive the week
Each one needs a named owner, a date, and a ticket. Prefer changes that remove the possibility over changes that ask people to be more careful:
- Good: the pipeline refuses to deploy when a migration is pending
- Weak: remind the team to check migrations before deploying
Cap the list. Five actions that ship beat fifteen that are still open at the next incident.
Timing
Draft within two days, while the detail is recoverable from memory and from logs that have not rotated. Circulate before the review meeting so the meeting is spent on the factors rather than on reconstructing the timeline.