Postmortem template: a blameless incident postmortem you can copy

A postmortem (also called an incident review or post-incident review) is a written account of an incident and of what the team will change because of it. It is written after the incident is resolved, not during it.

Blameless means the document looks for causes in systems and processes, not in people. The assumption is that everyone involved acted reasonably given what they knew at the time. If an engineer ran a command that took the database down, the useful questions are why that command was possible, why nothing warned them, and why recovery took as long as it did.

This is not about being kind for its own sake. People who expect blame stop reporting near misses, leave out awkward details and fix symptoms quietly. People who expect a fair review tell you what really happened, which is the only way to find the real causes.

A few habits help:

• Name roles or systems in the timeline ("the on-call engineer", "the deploy pipeline") rather than individuals.
• Replace "should have" with "what would have made the right action easier?"
• Hold a short review meeting, but treat the written document as the record.
• Share the finished incident postmortem widely. Others learn from it, and customers often appreciate a public version.

Copy this into your docs tool or repository and fill it in. Delete any section that genuinely does not apply rather than writing "N/A" everywhere.

# Postmortem: [short incident title]

Date of incident: YYYY-MM-DD
Authors: [names or roles]
Status: Draft / In review / Final
Severity: [SEV1 / SEV2 / SEV3]

## Summary
[2 to 3 sentences: what broke, for how long, who was affected, how it was fixed.]

## Impact
- Duration: [start time to end time, with time zone]
- Users or customers affected: [number or share]
- Symptoms: [errors, slowness, data issues]
- Data loss: [yes / no, details]
- Business impact: [revenue, SLA credits, support volume]

## Timeline (all times in [time zone])
- HH:MM  [First signal, e.g. alert fired or customer report]
- HH:MM  [Incident declared, responder assigned]
- HH:MM  [Key diagnosis steps and decisions]
- HH:MM  [Mitigation applied]
- HH:MM  [Service restored and confirmed]

## Root cause
[The technical trigger, in plain language.]

## Contributing factors
- [Condition that allowed the trigger to cause harm]
- [Gap in testing, monitoring, process or documentation]

## Detection
[How we found out, and how we could have found out sooner.]

## What went well
- [...]

## What did not go well
- [...]

## Where we got lucky
- [...]

## Action items
| Action | Type (prevent / detect / mitigate) | Owner | Due date | Ticket |
|---|---|---|---|---|
| [...] | [...] | [...] | [...] | [...] |

## Lessons learned
[Anything worth sharing beyond this team.]

The timeline is the backbone of the postmortem. Build it from records, not memory: alert history, deploy logs, error tracker events, chat messages in the incident channel and status page updates.

• Use one time zone and say which at the top. Mixing UTC and local time is an easy mistake to make.
• Start before the incident was declared. The first sign is often earlier than anyone realised: a warning in the logs, a spike in one error, a single customer email. The gap between first signal and declaration is one of the most useful things a postmortem can reveal.
• Record decisions, not just events. "14:12 rolled back the deploy" is an event. "14:12 rolled back because error rates matched the deploy time; the migration was not yet suspected" explains why the next step was taken.
• Mark the key moments so you can measure them: first signal, detection, response started, mitigated, resolved.
• Keep it factual. Opinions and analysis belong in the root cause and contributing factors sections.

From the timeline you can read off time to detect, time to mitigate and time to resolve. Tracking these across incidents shows whether your response is improving.

The five whys technique starts from the failure and asks "why?" repeatedly until you reach something you can change. Five is a guide, not a rule.

1. Why did checkout fail? The payment service returned errors.
2. Why? It could not reach its database.
3. Why? The connection pool was exhausted.
4. Why? A new background job opened connections and never released them.
5. Why was that not caught? The test environment runs with a far smaller workload, so the leak never filled the pool before tests finished.

The last answer points at a fix that prevents a whole class of problem, not just this bug.

Five whys has a known weakness: it produces a single chain, and real incidents rarely have one cause. Complex systems usually fail when several conditions line up. That is why many teams now record contributing factors alongside the root cause: the missing alert, the runbook that was out of date, the deploy that went out late on a Friday, the dashboard nobody checked. Each one is a place where the incident could have been prevented, caught sooner or made smaller.

Stop asking why when the answer becomes "a person made a mistake". Ask instead what would have made the mistake impossible or harmless.

A postmortem without completed action items is a story, not an improvement. Most teams find the writing easy and the follow-through hard.

• One owner per action. A named person, not a team. Shared ownership usually means no ownership.
• A due date. Urgent fixes in days, structural changes within a planned period. Without a date the item drifts behind feature work.
• A ticket. Put each action in your normal issue tracker, linked from the postmortem, so it competes for priority like any other work.
• Specific and checkable. "Improve monitoring" cannot be closed. "Alert when connection pool usage exceeds 80% for five minutes" can.
• A mix of types. Label each as prevent, detect or mitigate. If every action is "prevent", you have not planned for the next incident that gets through.
• Few enough to finish. Three to five well-chosen actions beat fifteen that nobody completes.

Review open postmortem actions at a regular meeting until they are closed, and note in the document when each one ships.

This is a made-up incident for illustration. The company, times and numbers are fictional.

Summary. On a Tuesday, sign-ups failed for 47 minutes because a configuration change removed the email provider's API key from production. New users saw an error on the final step. Rolling back the change restored service.

Impact. 47 minutes. Roughly 130 sign-up attempts failed, and about 40 of those users retried successfully after the fix. No data was lost.

Timeline (UTC).

• 10:02 Configuration change deployed to rename environment variables.
• 10:05 First customer email reports "error at the last step".
• 10:31 Error tracker alert fires once the error count passes its threshold.
• 10:36 On-call engineer links the errors to the 10:02 deploy.
• 10:49 Rollback deployed and sign-ups confirmed working.

Root cause. The rename changed the variable's name in code but not in the production environment settings, so the email client started without a key.

Contributing factors. No startup check for required variables; the alert threshold was too high for a low-volume flow; the customer email sat in a shared inbox for 26 minutes.

Action items. Fail the deploy if a required variable is missing (owner: platform lead, 2 weeks). Alert on any sign-up error, not a count (owner: on-call lead, 1 week). Route error reports from support straight to on-call (owner: support lead, 1 week).

OpenHelm runs an incident agent for each live product. A Sentry issue, or a customer's bug report by email, wakes it straight away. It first checks the report is real, made in good faith and not in conflict with a decision already made, then reproduces the problem, fixes it, tests, deploys, verifies the fix in production and resolves the issue. If the fix is merged but not yet live, it leaves the issue open with a comment. If it cannot fix it, it files one task with what it found.

A separate verifier judges each run from its tool-call record rather than from the agent's own summary. Each run also keeps a timestamped log, which is a useful starting point when you write the timeline for your postmortem. See bug fixing.