How to Write an Incident Postmortem: Template & Example

An incident postmortem records what happened, its impact, why defenses failed, and which tracked actions reduce recurrence or improve response. It is evidence-driven and distinct from a routine sprint or project retrospective.

The incident, people, services, metrics, and tickets below are fictional. Copy the incident-specific structure in this guide, then adapt access, review, and publication rules to the incident's sensitivity.

The cultural prerequisite: blameless

Before anyone writes a template, the team has to agree on one thing: post-mortems are blameless. That means:

• The focus is on systems, processes, and decisions — not individuals.
• We assume people did the best they could with the information they had at the time.
• Hindsight is not evidence. "You should have known" is not a valid criticism.
• Participation and reporting expectations are clear, including how sensitive or personnel issues are escalated outside the learning review.

Blameless does not remove accountability. Personnel concerns require the organization's established management and human-resources process, separate from the technical learning review. The post-mortem stays focused on "what can we change in the system to prevent this class of incident."

If your organization can't commit to blamelessness, post-mortems will be theater. People will cover themselves, withhold information, and assign vague action items. Nothing will improve. Fix the culture first.

When to write one

Write a post-mortem for:

• Any customer-facing incident (outage, data loss, major bug in production)
• Security incidents, using the security response process and appropriate access controls
• Any missed launch or significantly missed deadline
• Any "near miss" — something that almost went wrong and shouldn't happen again
• Any project, at its conclusion (this is the retrospective flavor)

You do not need one for:

• Individual bugs caught in code review or QA
• Minor delays inside a sprint
• Expected failures in a controlled environment (load testing, chaos engineering)

A good heuristic: if you'd want someone joining the team next year to know about it, write one.

The structure

A post-mortem has six sections:

1. Summary — what happened, at a glance
2. Timeline — what happened, with times
3. Root causes — why it happened
4. Impact — what it cost
5. What went well, what didn't — the reflection
6. Action items — what we'll do

The walkthrough below provides an incident-specific starting point for each section.

1. Summary

3–5 sentences at the top. Someone reading only the summary should know:

• What happened (the user-visible symptom)
• When and for how long
• Who was affected
• What the root cause was
• What we're doing about it

Fictional, illustrative example:

Summary: On 2026-03-15 from 14:22 to 15:47 UTC (1h 25m), the checkout API returned 500 errors for approximately 8% of requests. Root cause was an expired TLS certificate on our payment provider's staging environment that was inadvertently used in production due to a feature flag mis-configuration. All affected customers were retried successfully. We are adding certificate expiration monitoring and tightening feature flag environment checks.

2. Timeline

A chronological list with timestamps. Times in UTC for shared context.

## Timeline

All times UTC.

- **14:22** — Payment processor starts returning TLS errors. Not yet detected.
- **14:24** — First checkout 500 errors appear in logs.
- **14:31** — PagerDuty alert fires (checkout error rate > 5%).
- **14:33** — On-call engineer @alice acknowledges; opens incident channel.
- **14:41** — @alice identifies payment provider as upstream cause.
- **14:49** — @bob joins; notices staging endpoint in config.
- **14:52** — Feature flag rollback initiated.
- **15:14** — Rollback completes; the error rate begins to drop.
- **15:47** — Monitoring confirms the error rate is back to baseline; incident closed.

Rules for the timeline:

• Fact, not judgment. "Error rate dropped" — not "we quickly fixed the issue."
• Times in UTC. If the team is distributed, local times are confusing.
• Attribute responders by initial or handle, not full names. Keeps the focus on roles.
• Include detection gaps. The time between the problem starting (14:22) and the alert firing (14:31) is data. Nine minutes of undetected errors is an action item candidate.

3. Root causes

Root causes are why the incident happened, separated from the symptoms. Use the "5 Whys" technique to dig past the first layer.

Surface cause: "Feature flag pointed to staging." Why? Config file was copied from a test environment. Why? No CI check validates environment-specific values. Why? The config system doesn't have environment awareness.

A good root cause section distinguishes between:

• Trigger — the specific change or event that started the incident
• Contributing factors — conditions that made the incident possible or worse
• Detection gaps — why it wasn't caught sooner
• Response gaps — why it wasn't fixed faster

Incidents almost always have multiple root causes. "The cert expired" is a cause. "Our monitoring didn't catch cert expiration" is also a cause. Both get listed.

4. Impact

Quantified, specific:

• Customer impact: "~2,400 checkout attempts failed. ~1,900 retried successfully. ~500 abandoned and have been contacted by support."
• Financial impact: "Estimate pending finance review; methodology linked in the appendix."
• Internal impact: "On-call team paged for 1h 25m. Engineering time spent: ~12 person-hours across 4 engineers."
• Data integrity: "No data loss. 3 partial orders are being manually reconciled."

Impact should use verified counts, ranges, and timestamps. Label estimates and explain their method; minimize personal data.

5. What went well, what didn't

Usually two bullet lists. This is the retrospective heart of the document.

What went well:

• Alert fired within 9 minutes of the first error.
• On-call engineer identified the upstream cause quickly.
• Rollback mechanism worked as designed.
• Support was looped in within 15 minutes.

What didn't:

• Cert expiration wasn't monitored — a preventable root cause.
• Config file didn't fail a CI check despite pointing to staging.
• Status page was updated 20 minutes after incident started.
• No runbook for payment provider incidents; engineer worked from first principles.

Be specific. Every bullet should point to a concrete moment or artifact, not a general feeling.

6. Action items

Where most post-mortems fail. Action items are commitments, not wishes.

Each action item gets:

• An owner (one person)
• A priority (P0 / P1 / P2)
• A due date
• A ticket number (not a bullet in a Google doc — a tracked item in Jira, Linear, GitHub Issues, whatever you use)

Template:

## Action items

| Owner   | Priority | Due       | Item                                                  | Ticket   |
| ------- | :------: | --------- | ----------------------------------------------------- | -------- |
| @alice  |   P0     | 2026-03-22| Add cert expiration monitoring for all prod endpoints | INFRA-312|
| @bob    |   P1     | 2026-04-01| CI check for environment-specific config values       | PLAT-204 |
| @carol  |   P1     | 2026-03-25| Write payment provider incident runbook               | OPS-189  |
| @dave   |   P2     | 2026-04-15| Reduce detection time — error rate alert threshold    | OBS-77   |

Categories of action items:

• Prevent the same failure (primary goal)
• Detect sooner (reduce time-to-detection)
• Mitigate faster (reduce time-to-resolution)
• Communicate better (internal and external)
• Document (runbook, onboarding, decision record)

Track every action item in a dashboard. Review open items at every subsequent retrospective. An action item that ages out without being completed is a red flag — either it wasn't important, or the ownership is broken.

Facilitation

The document structure matters, but so does the meeting.

Before the meeting:

• The facilitator (often a service owner or team lead) drafts the timeline and a first-pass root cause analysis.
• Share the draft early enough for participants to correct facts; the appropriate lead time depends on urgency and availability.

During the meeting (adapt timing to incident complexity):

1. Review the timeline. Participants fill gaps and distinguish facts from hypotheses.
2. Analyze contributing factors. Use Five Whys, fault trees, or another suitable method.
3. Review response strengths and gaps. Invite input without forcing public disclosure.
4. Define actions. Assign an owner, priority, due date, and tracking item.
5. Close. Agree who reviews, publishes, and follows up.

Rules of engagement:

• Choose in-person, remote, written, or hybrid participation based on accessibility and team needs.
• Let people contribute synchronously or asynchronously, especially across time zones.
• Facilitator gently interrupts blame-shaped language: "Let's focus on what the system allowed, not who pushed the button."
• If emotions run hot, pause. Reconvene the next day if needed.

Publishing

Internal post-mortems go in a shared folder, linked from your incident management tool. Searchable, discoverable, part of onboarding.

Customer-facing postmortems are a reviewed subset of the internal record. Security, privacy, legal, support, and communications reviewers may need to approve disclosure. Include:

• What happened (in customer terms, not internal jargon)
• When and for how long
• What you're doing about it
• An apology, if warranted

Do not publish secrets, exploitable detail, personal data, unverified causes, internal handles, or raw logs. Follow applicable notification and disclosure processes. Customers want to know they're in good hands, not rubberneck your process.

Templates vs. reality

No template fits every incident. A network partition post-mortem and a missed marketing launch post-mortem have the same structure but very different content. Use the template as a skeleton, not a cage. If a section doesn't apply, omit it. If an incident needs a section the template doesn't have (e.g., "regulatory disclosure timeline" for a security incident), add it.

The template serves the goal. The goal is learning.

Running retrospectives (not incident-driven)

Retrospectives follow the same structure with lighter weighting:

• What we did (the project or sprint, briefly)
• What went well
• What didn't
• What we'd do differently
• Action items

Common formats:

• Start, Stop, Continue — what to start doing, stop doing, keep doing
• Mad, Sad, Glad — what frustrated people, disappointed them, delighted them
• Sailboat — what's moving us forward, what's holding us back

For ongoing teams, choose a retrospective cadence that produces useful learning without becoming ceremony. Incident postmortems remain event-driven. The point is to notice problems early, not clean up after disasters.

Anti-patterns

Watch for these failure modes:

• The "always on time next time" action item. Vague promises without mechanisms don't change anything. "Add CI check for X" changes things.
• The meeting that produces no document. If it's not written down, it didn't happen.
• The document nobody reads. Indexed, searchable, linked from onboarding — or it's wasted effort.
• Private finger-pointing after the meeting. Symptom of insufficient blamelessness in the room.
• The "we'll fix it later" that never happens. Every action item without an owner and due date.

Closing

The test of a good post-mortem isn't the meeting or the document. It's whether the same class of incident happens again in six months. If it does, your action items didn't stick — either they were wrong, they weren't owned, or they weren't executed.

Treat every post-mortem as an investment in the team's future speed. Incidents are going to happen. What separates mature teams from immature ones is whether they compound the lessons.