how to do a postmortem that changes things

TL;DR

Write the postmortem within 48 hours, name the systemic causes (never the person), and turn every lesson into an action item with an owner and a due date. Postmortems that change things end with work assigned, not feelings processed. Blameless is a method: ask what let the mistake happen, not who made it.

Error / query

how to do a postmortem that changes things

The incident is over and now comes the part most teams skip or phone in. You want a postmortem that actually prevents the next one.

Use this skill when

• a significant incident just resolved and the postmortem is due
• past postmortems produced documents nobody acted on
• the team blames people instead of systems in reviews
• you need a postmortem template that forces action items

Not for this skill when

• the incident is still active (work the incident first)
• you need the incident review meeting agenda (a different skill)
• you need to track action items already written (see the action items skill)

Steps

1. Gather the timeline first

A postmortem without a timeline is a postmortem built on vibes. Pull the incident timeline before writing anything.

ls ./incident-timeline.md && wc -l ./incident-timeline.md

Expected: the timeline file exists with enough entries to reconstruct the incident in order. If its thin, fill the gaps from chat history now, not later.

2. Fill the blameless template

Write the summary, paste the timeline, name systemic causes only, and convert every lesson into an owned action item. No names in the causes section, ever.

cat > ./postmortems/2026-10-04-postmortem.md <<'EOF'
# Postmortem: [incident title] - 2026-10-04

## Summary
[2-3 sentences: what happened, impact, duration]

## Timeline
[paste the incident timeline here]

## Root causes
[systemic causes only; no names]

## What went well
[what the response got right; protect it]

## Action items
| item | owner | due |
| ---- | ----- | --- |
| [fix] | [name] | [date] |
| [fix] | [name] | [date] |
EOF
cat ./postmortems/2026-10-04-postmortem.md

Expected: a complete postmortem draft with systemic causes and every action item carrying an owner and a due date. Items without owners get deleted or assigned now.

3. Review action items weekly until they are done

The postmortem isnt finished when its written; its finished when the action items are. Grep the open items every week.

grep -h "|\s*\[ \]" ./postmortems/*.md 2>/dev/null | head -20
echo "--- open action items above; review weekly until this list is empty ---"

Expected: a visible list of open action items. The postmortem process ends when this list is empty, not when the doc is merged.

Variant phrasings

blameless postmortem template

Same fix: the template in step 2 is blameless by construction. Systemic causes, no names, owned action items.

how to write an incident retrospective

Same fix: timeline, systemic causes, what went well, action items with owners. The retrospective that changes things is the one that assigns work.

postmortem best practices

Same fix: within 48 hours, blameless, timeline-driven, and action items tracked to done. Everything else is formatting.

Why it happens

Postmortems fail when theyre theater: a doc written to satisfy process, with lessons that evaporate because nobody owned them. Writing the item down felt like doing it. Blamelessness fails when "no blame" becomes "no causes named at all", which teaches nothing. The method works when causes are systemic, specific, and attached to owned work with dates.

Edge cases and pitfalls

• SEV3 not worth a full postmortem: do a 15-minute mini-retro with the same template, fewer sections.
• Someone wants to name names: redirect to systems every time. "What let this happen" is the only allowed question about causes.
• Action items never get done: review them in sprint planning, not in a side doc. Side docs are where items go to die.
• Legal or compliance constraints on wording: keep a factual internal version separate from any external summary.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_1hDENGhyr1wxKkt4RotEPw