Incident postmortem: what to include (with a template)

The incident is resolved, the service is back, everyone relaxes. That is exactly the moment most teams let go of what the outage could have taught them. Three days later, nobody remembers precisely when the first alert fired, which command finally fixed things or why it took forty minutes to understand what was going on. A postmortem pins those facts down in writing and turns them into concrete actions.

This article walks through what a good postmortem contains, section by section, with a template you can copy, examples of phrasing to avoid, and how to turn the internal document into a public version for your status page.

Blameless, or pointless

A postmortem is worthless if the people involved are afraid to describe what actually happened. The blameless approach starts from a simple assumption: everyone acted reasonably given the information they had at the time. If a single command was enough to take production down, the real question is not "who ran it?" but "why did the system let it have that effect?".

The chapter on postmortem culture in Google's SRE book explains this well and is still the reference on the subject. The key point: blameless does not mean without accountability. Every corrective action has a named owner and a due date. You are not looking for a culprit, you are looking for improvements, and someone has to carry each one.

When to write a postmortem

Not every incident deserves a three-page document. Agree on criteria in advance so the decision does not depend on the mood of the day. A postmortem is usually warranted when:

• the service was unavailable or badly degraded for users beyond a duration you have set, say fifteen minutes;
• data was lost or corrupted, even partially;
• an emergency manual intervention was needed: rollback, restore, failover;
• a customer reported the outage before your own alerts did;
• the incident burned a significant share of your error budget (see our guide to SLA, SLO and SLI);
• the team came close to a serious outage, even with no visible impact.

Aim for a first draft within 48 hours, while memories are fresh, and a team review within the week. Writing it usually falls to whoever led the response, not necessarily to whoever triggered the incident.

The sections of a complete postmortem

Summary

Three to five sentences that someone who followed nothing can understand: what broke, for how long, for whom, why in one line, and whether it is fixed. Many readers will stop here.

Impact, in numbers

Replace "some users" with figures: duration of the outage, share of failed requests, number of failed orders or logins, affected regions, support tickets received. If you only have an estimate, say so and give the range. State what was not affected too; it is often just as useful.

Timeline, in UTC and local time

Log every timestamped event: first symptom, alert, acknowledgement, hypotheses tested, fix, return to normal. Write times in UTC, with local time in brackets if your team or customers think in their own time zone. It pays off the day an incident straddles a daylight saving change.

Detection: how, and how fast

Who or what noticed first: a monitoring alert, a customer, a colleague by chance? Measure three delays: from the real start to detection, from detection to acknowledgement, and from acknowledgement to resolution. The first one is often the most revealing: slow detection points to a gap in your monitoring, not to a lack of responsiveness.

Root cause and contributing factors

Incidents rarely have a single cause. Describe the trigger, then the conditions that let it do damage: an undersized limit, a missing alert, a deployment process with no safety check, outdated documentation. The "five whys" technique helps you work back up the chain, as long as you stop at causes you can actually fix.

What went well, what went badly

Record what worked (the rollback took two minutes, the alert reached the right person) so you keep it, and what got in the way (missing access, a dashboard nobody could find, a late customer message).

Action items, with owners and dates

Each action is written as a verifiable task, with a named owner, a due date and a link to the matching ticket. Group them: what prevents a repeat, what speeds up detection, what limits the impact next time. Four completed actions beat fifteen good intentions.

A template to copy

Here is a Markdown template, filled in with a fictional example to show the level of detail to aim for.

# Postmortem: payments unavailable after a deployment

Status: reviewed 26 Sep · Author: incident lead · Internal version

## Summary
On 23 Sep, from 14:02 to 14:49 UTC (16:02 to 16:49 Paris time), checkout
failed for every customer. A configuration change shrank the database
connection pool. The release was rolled back and the cause fixed.

## Impact
- Duration: 47 minutes of checkout unavailability
- Failed requests on /checkout: 100% for 47 min
- Failed orders: 312 (estimated from abandoned carts)
- Not affected: browsing, customer accounts, back office
- Support tickets: 41

## Timeline (UTC, Paris time in brackets)
- 13:58 (15:58) Version 4.12 deployed
- 14:02 (16:02) First 500 errors on /checkout
- 14:04 (16:04) Outage confirmed by monitoring, alert sent
- 14:09 (16:09) Alert acknowledged by the on-call engineer
- 14:31 (16:31) Connection pool identified as the probable cause
- 14:44 (16:44) Rolled back to version 4.11
- 14:49 (16:49) Error rate back to normal

## Detection
- Detected by: external monitoring (keyword check on /checkout)
- Time to detect: 2 min · to acknowledge: 5 min · to resolve: 40 min

## Root cause and contributing factors
- Trigger: pool size changed from 50 to 5 in a shared config file
- Factor: code review did not cover configuration files
- Factor: no load test on the staging environment
- Factor: no metric on connection pool usage

## What went well / badly
+ Alert received within 2 minutes, rollback done in 5 minutes
- 22 minutes spent investigating the payment provider
- Status page message only published at 14:35

## Action items
| Action                                       | Owner   | Due    | Ticket |
|----------------------------------------------|---------|--------|--------|
| Make config files part of mandatory review   | Team A  | 30 Sep | OPS-81 |
| Alert on connection pool usage (> 80%)       | Team B  | 3 Oct  | OPS-82 |
| Load test before every production release    | Team A  | 15 Oct | OPS-83 |
| Status message within 10 min (procedure)     | Support | 30 Sep | OPS-84 |

Good and bad phrasing

Wording does a lot for both the blameless spirit and the usefulness of the document. A few examples:

The general rule: measurable facts, mechanisms rather than people, verifiable actions rather than intentions.

Internal version, public version

The internal document holds everything: server names, log excerpts, discarded hypotheses, exchanges with vendors. Your customers need something else. The public version, the one you post on your status page or send to clients, fits in a few paragraphs:

• what happened, in plain language;
• when, with start and end times and the time zone;
• who was affected and how: which features, which regions;
• what you did to restore service;
• what you are changing so it does not happen again.

A status page that shows past incidents with this kind of explanation builds more trust than one that is always green.

Following up on action items

A postmortem whose actions stay open for six months was only a way to feel better. A few simple habits help:

• copy every action into your usual ticketing tool, not just the document;
• review open actions in a regular meeting, weekly or fortnightly;
• only mark the postmortem as closed once every action is done or explicitly dropped, with the reason;
• reread the last few months of postmortems together: recurring causes deserve a dedicated project.

How LucidStack helps with postmortems

The most tedious part of a postmortem is rebuilding the timeline. In LucidStack, every incident keeps its own timeline of events: failed checks, affected regions, the confirmed outage, acknowledgement by whoever is on call, recovery. Your detection and acknowledgement delays are right there, without digging through chat history.

Each incident has a dedicated postmortem field, and you can export the incident as a PDF with its whole timeline, handy for your archives or for sending to a client. If you want, AI incident analysis writes a structured first draft (facts, timeline, impact, cause, actions) and a public message for your status page, based on the monitoring data. Treat it as a draft: review it, correct it and add what monitoring cannot know, such as the context of the deployment or what your customers told you. AI can also be turned off for the whole organization.

A good postmortem needs no special tool, only rigour. Having the timeline and a draft ready simply leaves you more time for what matters: understanding and fixing.