How to Write a Postmortem That Changes Something

Most postmortems get filed and forgotten. They read like a press release, they end with "improve monitoring," and three months later the same failure returns with a new ticket number. The ones that change something look different. They are specific, a little uncomfortable, and finished with action items that have owners and dates.

This is a structure you can follow after a real incident. Fill every section with facts. If a section is empty because you do not know yet, write that down instead of inventing confidence.

What separates a useful postmortem from a filed one

A useful postmortem does three jobs.

1. It records what happened with enough precision that a future engineer can trust the timeline.
2. It separates the root cause from the conditions that let the root cause matter.
3. It produces changes in the system, not vibes about trying harder.

If your document only does job one, it is a diary. If it skips job three, it is theater. Aim for all three.

1. Incident summary

Two or three sentences. What broke, when, how long, and what customers felt.

Good. "On 12 Feb 2026 from 14:32 to 15:52 SGT, the payments API returned 503s for approximately 18% of checkout requests after a connection pool exhaustion on the primary PostgreSQL instance. About 2,400 checkouts failed. No data loss."

Common mistake. A long narrative that softens impact, or a summary that reads like customer marketing. Save detail for the timeline. The summary is for people who will read nothing else.

2. Timeline

Use machine-precise timestamps where you can. Pull them from alert systems, deploys, and logs. Do not reconstruct from memory if the tools still have the record.

Example shape.

• 14:32 Alert fired. Payments API error rate above threshold from Singapore and Tokyo.
• 14:38 On-call acknowledged.
• 14:51 Incident declared P1. Status page set to degraded.
• 15:05 Root cause identified. Primary DB connection pool saturated.
• 15:21 Mitigation. Reduced worker concurrency and recycled stuck app pods.
• 15:47 Fix deployed. Pool max raised and checkout path timeout adjusted.
• 15:52 Recovery confirmed. Error rate back to baseline for 10 minutes.

Common mistake. Approximate times ("around 3") and missing ack or status-page events. Those gaps hide response delays you need to fix.

3. Root cause

Root cause is the thing that, if corrected, would have prevented this incident in these conditions. Most teams stop one layer too early and label a symptom as the cause.

Symptom dressed up as root cause. "The database ran out of connections."

Actual root cause worth writing. "The payments API had no upper bound on concurrent DB connections per pod. A traffic spike after a marketing email created more pods and more connections than the primary could accept, which exhausted the pool and caused checkout 503s."

Common mistake. Stopping at the first red metric. Keep asking what allowed that metric to become an outage until you hit a concrete design or process gap you can change.

4. Contributing factors

These are the conditions that let the root cause become customer impact. They are not soft blame. They are the second and third levers you can pull.

Examples that belong here.

• No alert on connection pool saturation, only on HTTP 5xx rate.
• Load test coverage did not include the marketing-email traffic shape.
• Checkout path had no shed-load behavior when the DB pool was exhausted.
• Recent pool settings change shipped without a canary.

Common mistake. Mixing contributing factors into root cause until the section becomes a fog of "many things." Keep one primary root cause. List the enablers separately.

5. Impact

Quantify when you can. Users affected, minutes of customer-visible downtime, failed transactions, support ticket volume, SLA credit risk.

Good. "2,400 failed checkouts over 80 minutes. 140 support contacts. Enterprise SLA for Acme still inside monthly budget. No security exposure."

Common mistake. "Some users were impacted." That sentence cannot prioritize action items or inform customers honestly later.

6. What went well

This section is not courtesy. It captures response strengths you want to keep.

Examples.

• Multi-region alert confirmation avoided a false page from a single probe.
• On-call acknowledged in six minutes.
• Status page updated before root cause was known.
• Secondary engineer joined from the escalation policy without a Slack scavenger hunt.

If nothing went well, say so briefly. Empty praise wastes trust.

7. What went wrong

Specific and factual. No character judgments.

Good. "The runbook still pointed at the old failover script path, so the first mitigation attempt failed."

Not useful. "Jordan panicked and made it worse." Even if the room felt that way, rewrite it as a system problem. Unclear ownership, missing rehearsal, or a dangerous script with no dry run.

For the framing discipline behind this, see blameless does not mean consequence-free.

8. Action items

This is where most postmortems die. Format is non-negotiable.

Each action item needs

• a specific description of the change
• a single named owner
• a due date

Broken. "Improve monitoring."

Done. "Add a warning and page alert on payments primary connection pool usage above 80% for 5 minutes. Owner. Priya N. Due. 26 Feb 2026."

Track these in the same system you use for real work. A checklist at the bottom of a doc that nobody opens again is not a plan.

9. Lessons learned

One or two durable insights that apply beyond this incident. Not a repeat of the root cause.

Good. "HTTP 5xx alerts are too late for pool exhaustion. Dependency saturation needs its own signal."

Weak. "We should be more careful during launches." That lesson evaporates by next quarter.

A note on blameless framing

Blameless means you aim accountability at the system so people tell the truth. It does not mean nothing changes. Action items still have owners. Risky shortcuts still get removed. The difference is that the write-up does not organize itself around who to punish.

If people are sanding the timeline to protect themselves, you will not get a root cause worth fixing. Fix the fear first, then demand precision.

Plain-text postmortem template

Copy this into your doc tool and fill every field.

INCIDENT POSTMORTEM

Title:
Date of incident:
Authors:
Severity:
Status: (draft | reviewed | actions tracked)

1. SUMMARY
(2-3 sentences: what, when, duration, customer impact)

2. TIMELINE (timezone: )
- HH:MM Event
- HH:MM Event

3. ROOT CAUSE
(What actually caused the incident. Not just the first symptom.)

4. CONTRIBUTING FACTORS
-
-
-

5. IMPACT
- Users / customers affected:
- Duration of customer-visible impact:
- Failed transactions or key business metric:
- Data loss / security impact:
- SLA / contractual impact:

6. WHAT WENT WELL
-
-

7. WHAT WENT WRONG
-
-

8. ACTION ITEMS
| Action | Owner | Due date | Status |
| ------ | ----- | -------- | ------ |
|        |       |          |        |

9. LESSONS LEARNED
-
-

How long it should take, and who should write it

A solid first draft for a medium incident should take one to two focused hours if the timeline tools still have the events. The primary writer is usually the incident commander or the primary responder, not a manager summarizing secondhand. Managers review for clarity and follow-through. They should not sand the facts.

Schedule the review meeting after the draft exists. A meeting with no draft becomes storytelling. A meeting with a draft becomes editing and action-item assignment.

Close the loop in a fixed window. For most teams, action items from a P1 should be reviewed again two weeks later. If half are still "in progress" with no commit or ticket, the postmortem did not change anything yet. Fix the follow-through process before you write another polished doc.

Write the draft while the timestamps still exist

The best time to start a postmortem is as soon as the incident is stable, while alert history and chat timestamps are still easy to pull. Waiting a week trades precision for comfort, and comfort is how action items turn vague.

Vigiles can auto-draft a postmortem from the incident timeline so the first version already has alert, ack, and restore markers for the team to edit. The judgment still belongs to your engineers. The template above is how you keep that judgment honest and finish with changes that land.