Postmortem Template That Encourages Honesty

Shawn West

Jun 21

6 min read

Updated: Jul 13

A postmortem template can't fix a culture, but it can nudge a team toward honesty by giving them prompts that are hard to answer without it. The template below is structured to surface what's usually hidden: the human factors, the latent system risks, the prior near-misses everyone forgot. It also resists the most common postmortem failure mode — turning the document into a defensive narrative.

The Working Template

# Postmortem: [Short title]

Date of incident: YYYY-MM-DD
Date of postmortem: YYYY-MM-DD
Authors: [names]
Status: [Draft / Final]

## Summary
[2-3 sentences. What happened, how long, who was affected.]

## Impact
- Customer-visible impact: [specific]
- Duration: [start, mitigation, resolution]
- Affected systems: [list]
- Affected populations: [users, internal, partners]

## Timeline
[Chronological list of events with timestamps. Include detection, escalation, mitigation attempts, resolution.]

## Root Cause
[The technical cause and the contributing factors. Not just the trigger.]

## What Went Well
[Things that limited the blast radius or accelerated recovery.]

## What Went Wrong
[Things that worsened the impact or delayed recovery.]

## Where We Got Lucky
[Honest section. What could have been worse if not for chance.]

## Action Items
| Action | Owner | Due | Priority |
|--------|-------|-----|----------|
| [Specific change] | [Name] | [Date] | [P0-P3] |

## Lessons Learned
[Insights that apply beyond this incident.]

The Sections That Matter Most

Timeline: facts in chronological order. No interpretation. Just what happened, when, with timestamps.

This section feels mechanical, but it's where the postmortem earns its honesty. A clear timeline reveals delays you didn't realize had happened — "we noticed at 14:02 but didn't page anyone until 14:23." Don't soften the timeline; let it speak.

Where we got lucky: the section that distinguishes good postmortems from defensive ones. What could have been worse if not for chance? A small data corruption that happened on a Tuesday at 2pm instead of Friday at 5pm. A bug that triggered for 1% of users instead of 100%. A backup that happened to exist because someone set it up for a different reason.

This section catches the latent issues. The next time, the luck may not hold.

Root cause vs. trigger: distinguish them. The trigger is what happened (deploy at 13:47 included a query that locked the table). The root cause is the structural condition that made the trigger dangerous (no automated query review, deploys allowed during peak hours, table without partitioning).

Fixing only the trigger fixes nothing; fixing the root cause prevents the class of incident.

Blameless, Specifically

"Blameless postmortem" is a common phrase. What it actually means in the document:

Refer to roles, not people, where the role is what matters ("the on-call engineer noticed" rather than "Alice noticed")
Avoid language that assigns moral fault ("failed to," "should have known")
Focus on systemic and procedural factors, not individual judgment
Treat human error as a symptom, not a cause — ask what the system allowed

The point isn't to protect anyone. It's to keep the document focused on what's actionable. Blaming individuals produces defensiveness; analyzing systems produces fixes.

Action Items That Actually Get Done

Most postmortem action items don't get done. They live on a wiki page no one revisits.

Discipline that helps:

Specific, not aspirational. "Improve testing" vs. "Add an integration test that exercises the table-locking case." The first won't get done; the second might.
Owned by a single person. Joint ownership means nobody owns it.
Tracked in the team's normal work system. Jira, Linear, whatever. Not just in the postmortem doc.
Prioritized. Not every action is P0. A mix of priorities lets the team be honest about what's worth doing right now versus later.
Reviewed. Quarterly walk-through of open postmortem action items. Close them, deprioritize them, or escalate them — don't let them rot.

What Goes Wrong With Templates

A few patterns to watch for.

Box-checking. Engineers fill out each section to the minimum. The document looks like a postmortem but contains no substance. Counter by reviewing postmortems for quality, not just for existence.

Defensive narrative. The doc is written to make the team look good. Action items are small, root causes are blamed on external factors. Counter by including "where we got lucky" and by reviewing draft postmortems with skeptical reviewers.

Postmortem inflation. Every minor incident gets a full postmortem. The team burns out. Counter by tiering: full postmortems for major incidents, lightweight retrospectives for smaller ones.

No follow-through. Postmortems get written and filed. Action items never close. Counter by reviewing past action items in retrospectives.

When to Write One

Customer-visible outages beyond a defined threshold
Data integrity incidents
Security incidents
Anything that surprised the team
Near-misses that could have been bad

The threshold should be defined explicitly. "Anything user-visible over 15 minutes" or "anything that triggered a page" — pick a bar.

For smaller events, a short retrospective in a Slack thread is often enough. Reserve the full postmortem for events that deserve the investment.

Sharing the Postmortem

A postmortem locked in the team's wiki has limited value. Share it.

Within engineering: yes, broadly. Other teams learn from your incident.
With product and support: usually yes, especially if customer-visible.
With customers: depends on impact and contract. Some incidents warrant a customer-facing version (less technical detail, more about impact and what's changing).
With leadership: at least the summary.

Sharing has a side effect: it forces honesty. A postmortem that will be read by other teams is written with more rigor than one that won't.

Tiers of Postmortem

A working tiering scheme:

Level 1 (full postmortem): customer-impacting, data risk, security, multi-team
Level 2 (short retrospective): internal-only impact, single team
Level 3 (Slack thread): minor self-healing issues, no broad impact

Each tier has its own template depth. Level 1 uses the full template above. Level 2 is shorter. Level 3 is a paragraph.

The tiering prevents postmortem fatigue while keeping the discipline alive for the incidents that warrant it.

A Worked Example

# Postmortem: Checkout 500s on 2026-03-15

Date of incident: 2026-03-15
Authors: Pat, Sam

## Summary
A schema migration deployed at 14:00 acquired an exclusive lock on the orders table, blocking new orders for 43 minutes. Approximately 1,200 customers saw a 500 error during checkout. Revenue impact estimated at $48k.

## Impact
- Customer-visible: 1,200 failed checkouts
- Duration: 14:00 (start) - 14:23 (detected) - 14:43 (resolved)
- Affected: orders service, downstream notification service
- Affected populations: web checkout users only

## Timeline
- 14:00 Migration deploy begins
- 14:02 Lock contention starts; checkout 500s begin
- 14:05 Customer reports surface in support channel
- 14:23 On-call engineer paged
- 14:30 Cause identified
- 14:38 Migration cancelled
- 14:43 Service recovered

## Root Cause
The migration added a NOT NULL column with a default value, which on Postgres pre-11 required a full table rewrite under lock. Our orders table is 80M rows. The change was technically reviewed but the reviewer was not familiar with this specific lock behavior.

## What Went Well
- Customer support flagged the issue within 5 minutes
- Rollback was clean once we identified the cause

## What Went Wrong
- 23-minute gap between issue starting and engineer being paged (our automated alerts have a 20-minute threshold)
- Lock-acquiring migration had no test for table-size behavior
- The reviewer was the only sign-off; no operational reviewer

## Where We Got Lucky
- The incident happened during US business hours; support could escalate quickly
- The migration was reversible
- Marketing wasn't running a promotion; traffic was 60% of typical peak

## Action Items
| Action | Owner | Due | Priority |
| Reduce paging threshold for checkout errors to 5 minutes | Sam | 03-22 | P0 |
| Add migration linter rule for NOT NULL + default on large tables | Pat | 03-29 | P0 |
| Require operational reviewer for migrations on tables >10M rows | Lead | 04-05 | P1 |

## Lessons Learned
"Standard migration patterns" still depend on table size and database version. A migration that's safe on a small table isn't necessarily safe on a large one. Our migration tooling should encode this rather than relying on reviewer expertise.

Key Takeaway

A postmortem template prompts the honest analysis that culture allows. Include sections for timeline, what went well, what went wrong, where you got lucky, and specific action items with owners and dates. Distinguish trigger from root cause. Use blameless language to focus on systems, not individuals. Tier the postmortem investment to the incident severity. Track action items in the team's normal work system, not just in the document. Share broadly — postmortems written for wider audiences are written more honestly.