How to write an incident postmortem people will read
Turn an incident into a short, blameless account of what happened, why it got as bad as it did, and the few changes that will be made.
Run the response · 5 min read · Updated Oct 12, 2026
Most postmortems are written to be filed. They are long, they arrive three weeks late, they end in fourteen action items with no owners, and the same outage happens again in the spring.
A useful one is short, written within days, honest about what made the incident worse, and ends in two or three changes that somebody has agreed to make. This guide is about writing that one.
How it works
A postmortem answers four questions, in this order.
- What happened, and when? The timeline, as it looked to the people in it.
- Who was affected, and how badly? The impact, in numbers where you have them.
- What made it happen, and what made it worse? The contributing factors. There is almost never only one.
- What will change? A few actions, each with an owner.
It is blameless. That is not politeness: people who expect blame leave things out, and then the account is wrong. Write about what the system allowed, not about who pressed the button.
Step 1: Meet within days
Get the people who handled the incident together for half an hour, within a few days of it. Memory fades fast, and the order of events is the first thing to go.
Bring whatever recorded the incident: alerts, chat history, deploy logs, the status page updates. The meeting is for agreeing what happened, not for discovering it.
Step 2: Settle the timeline first
Start from the recorded events: detected, paged, acknowledged, each update, mitigated, resolved. Then add what no system recorded: when a customer first wrote in, when someone noticed the dashboard, when the wrong fix was tried.
Write each entry as what people knew at that moment, not what you know now. "Restarted the API, which did not help" is more useful than silence about the hour it cost.
Do this before anything else. The rest of the document is an argument about the timeline, and it goes better when the timeline is settled.
Step 3: State the impact plainly
Four things, in numbers and times:
| What | Write |
|---|---|
| Users or requests | Who was affected, or what share of traffic. |
| Where | Which regions or customers saw it. |
| Services | What was degraded and what failed outright. |
| Data | Whether anything was lost or corrupted. If nothing, say so. |
"Some users had issues" tells a reader nothing. "About one in five sign-ins failed for 40 minutes" does.
Step 4: Name the contributing factors
Looking for one root cause ends the inquiry at the first thing that went wrong. Look for four kinds of factor instead:
A certificate expired on the load balancer in front of the API.
No check watched that host. A customer told us 40 minutes in.
Every client retried at once, which kept the API down after the fix.
Nobody on call had access to the load balancer.
- Trigger: what set it off.
- Detection: why it took as long as it did to notice.
- Amplifier: what turned a small fault into a large one.
- Mitigation: what slowed the fix.
An incident with only a trigger listed has not been understood yet. The trigger is usually the least interesting part, because next time it will be a different one. Detection and amplifiers are where the lasting fixes are.
Step 5: Agree on a few action items
Keep the list short. Three things that are done beat twelve that are not.
A good action item:
- can be finished, and it is obvious when it has been;
- belongs to one person, who was in the room and agreed;
- changes the system, not people's vigilance. "Be more careful with deploys" is not an action. "Deploys stop automatically when the error rate doubles" is.
If something is worth knowing but will not be done, say so. That is more honest than leaving it open for a year.
Step 6: Write the summary last
The summary is the only part most people will read, and the part that can be shown to customers. Write it when everything else is settled: one paragraph on what happened, who was affected and how it ended. Lead with the impact. Keep it under about 80 words and free of internal names.
Step 7: Decide what customers see
Customers want three things: what they experienced, for how long, and that it is understood. They do not need the timeline or your action list. Publish the summary where they already look, which is the status page entry for the incident.
Before publishing, give the draft to someone who was not in the incident and ask two questions: what happened, and what is changing? If they cannot answer both, it is not finished.
Common mistakes
- Writing it weeks later. People no longer remember the order of things.
- Naming people. "The engineer on call restarted the wrong service" teaches the team to say less next time. "The two services have near-identical names in the console" can be fixed.
- Action items nobody owns. An item without a name next to it will not happen.
- A customer summary full of internal terms.
- Never looking at the action items again. Review the open ones at a regular time.
Doing this in saysOK
When you resolve a SEV-1 or SEV-2 incident, one that was posted to a status page, or one with comments, saysOK creates a postmortem draft from its timeline. Its sections follow the steps above: Summary, Impact, Timeline, Contributing factors with the four types, and Action items with a priority, an owner and a status.
Publishing needs a summary and at least one contributing factor. With the Status page option on, it shows the title and the summary under the incident on the status pages that list it, and it can email those pages' subscribers. Everything else stays internal, and people's names can be replaced with the team's.
Postmortems are part of every plan; see pricing for what each plan includes.
Next
A postmortem's most common action items are a missing alert and a slow page. See how to set up an on-call rotation for a small team, and for where the published summary appears, how to set up a status page on your own domain.
Set this up in saysOK
Start on the free plan. The guide says where a step needs a paid one.