---
name: "project_postmortems"
description: "Run a blameless postmortem after a project or incident: build a sourced timeline, drive a five-whys root-cause analysis, and produce action items with owners, due dates, and follow-through tracking. Use when reviewing something that shipped, broke, or finished."
---

# Project Postmortems

## Purpose

Turn a finished project or incident into learning the team actually keeps. The output is a written postmortem with a factual timeline, a five-whys analysis that ends at a system or process condition (never a person), and action items that get done because each one has an owner, a due date, and a tracking check.

Works for incidents and for plain project reviews (launches, migrations, experiments that underperformed). Run it soon: drafts written more than a few days after the event lose detail and honesty.

## Workflow

### 1. Gather facts before the meeting

Collect evidence from primary sources only: logs, metrics, commits, alerts, tickets, chat records. Draft the timeline from these sources first, analysis second. Label every entry with its source. Never mix a sourced fact and an interpretation in one sentence without flagging which is which.

If the team has memory to add, circulate the draft timeline a day ahead so people react to evidence instead of reconstructing from scratch.

### 2. Build the timeline

Chronological, with enough detail that someone reading it months later understands what happened. Cover the full arc:

| Marker | Project review | Incident |
| --- | --- | --- |
| Start | kickoff / plan commit | triggering change deployed |
| First sign | milestone slip, scope change | symptom, alert fired |
| Response | replans, escalations | mitigation attempts |
| End | ship / cancel / declare done | service confirmed healthy |

For incidents also note time to detect, time to mitigate, time to resolve. Quantify impact (how many affected, how long, revenue/SLA effect). If you cannot quantify, say so and give a best-effort estimate labeled as one.

### 3. Run the meeting (60 minutes, time-boxed)

Opening (5 min): state the ground rule once. We are here to learn, not to blame. A review that punishes honesty makes the next incident go unreported, which is worse than any bug.

Timeline review (15 min): walk the draft, take corrections, fill gaps. Record events, do not editorialize.

Analysis (20 min): for each failure or near-miss, run the five whys. Push every answer one level deeper until it lands on a system or process condition. "The reviewer missed it" is not a root cause; "the checklist had no item for that failure mode" is. If the whys bottom out at a person, keep going until you find the guardrail that should have existed.

Also ask: where did we get lucky? Correct outcomes produced by luck, not process, are future incidents. Each lucky break needs the gate that would catch it next time.

What went well (10 min): name the gates and responses that worked so they get reinforced, not accidentally dismantled.

Action items (10 min): brainstorm, then cut ruthlessly. See Output Contract.

### 4. Write it up

One document, filed within a day where the team actually reads its docs. Follow the template in `references/postmortem-template.md`. A worked example lives in `references/worked-example.md`.

### 5. Track the action items to done

A postmortem without follow-through is silence with paperwork. Schedule one follow-up check (meeting or async review) against the due dates. At the check, each item is done, moved with a reason, or marked failed with a new date. Publish the results back to the team.

## Output Contract

**The timeline** cites a primary source per entry. Entries without sources are flagged as recollection.

**The five whys** chain runs symptom -> ... -> system/process condition. Every chain terminates on something changeable (a checklist, a gate, a default, a review step), never a character judgment. Multiple chains are expected: most failures have more than one contributing factor.

**Action items**, each with five fields:

- **Owner**: a named role or person who agreed, not someone assigned in absentia.
- **Verb**: add, remove, update, test, deploy. Never "investigate" or "look into".
- **Measurable outcome**: what changes observably ("deploy canary step added to pipeline"), not "improve monitoring".
- **Tracker**: the ticket/PR/task ID it lives in.
- **Due date**: a date or release event.

Prefer items that become gates (a test, a check, a rule) over items that rely on memory. Cap the list at what the team can finish: three done items beat twelve open ones.

## Operating Rules

1. Blameless is a method, not a slogan. Redirect blame to systems: "the deployment introduced a regression", not "John broke production". Refuse blame-first framings; explain why they kill future reporting.
2. One exception: genuine repeated wilful misconduct is a leadership call, not a postmortem finding. Everything else gets the blameless treatment.
3. Quantify impact. "Some users were affected" is not an impact statement.
4. Cut the scope to what matters. Minor incidents get the quick template (see references), not the full meeting.
5. Skip nothing promised. A promised fix is not fixed until it is verified on the real surface: the test runs green, the gate fires, the checklist item exists.