Postmortem Document Schema

The structure for plans/incident-<date>-<slug>/postmortem.md (e.g. plans/incident-2026-08-14-checkout-outage/postmortem.md). Used by incident-postmortem Phases 2 and 5.

<!-- Generated by the incident-postmortem skill -->
<!-- Incident date: YYYY-MM-DD · Written: YYYY-MM-DD · Status: Draft | Reviewed -->

# Postmortem: <one-line incident name>

## 1. Summary

Three to five sentences: what broke, for how long, who was affected, how it was
resolved, and the single most important lesson. Written last, readable by
someone with no context.

## 2. Impact

- **Duration**: first user impact → full resolution (with timestamps, timezone stated)
- **Scope**: users / requests / tenants affected, with numbers where they exist
- **Functional impact**: what users could not do
- **Data / financial impact**: loss, corruption, SLA breach — or explicitly "none"
- **Severity**: 🔴 Critical / 🟡 Major / ⚪ Minor (shared severity scale)

## 3. Timeline

All times in one stated timezone. Facts only, each with a source.

| Time | Event | Source |
|------|-------|--------|
| 14:02 | Deploy `abc123` rolls out to 100% | deploy log |
| 14:07 | p99 latency on /checkout exceeds 5s | dashboard |
| 14:21 | **Detection**: first page fires | alerting |
| 14:25 | Responder begins investigating cache theory (dead end, 40 min) | chat log |
| 15:05 | Diagnosis: N+1 query introduced in `abc123` | chat log |
| 15:11 | **Mitigation**: rollback to `9fe771` | deploy log |
| 15:18 | **Resolution**: error rate back to baseline | dashboard |

**Derived intervals** — state them explicitly; they are findings:

- Time to detect: impact → detection (14:07 → 14:21 = 14 min, via alert not customer)
- Time to mitigate: detection → mitigation
- Time to resolve: detection → resolution

## 4. Contributing Factors

Never a single root cause. One subsection per factor, each classified:

### Factor 1: <name> — (defect | detection gap | amplification | response friction)

- **What**: the condition, stated blamelessly (system-focused, no names)
- **Evidence**: the timeline entries / artifacts that establish it
- **Why it existed**: the systemic answer from the iterative-why analysis

## 5. What Went Well

The safeguards, mitigations, and decisions that limited the damage — each one a
practice to keep, stated as concretely as the factors above.

## 6. Action Items

Every item: specific, prioritized on the shared scale, and routed.

| # | Action | Class | Priority | Route |
|---|--------|-------|----------|-------|
| 1 | Fix the N+1 query in `orders.repo` (evidence in §4.1) | defect | [P0] | debug-and-fix |
| 2 | Health-gated staged rollout for the checkout service | prevention | [P0] | prd.md → design-to-tasks |
| 3 | Alert on checkout p99 > 2s (detected in 14 min; budget is 5) | detection | [P1] | prd.md → design-to-tasks |

## 7. Appendix

Links to dashboards, log queries, the incident channel, related postmortems,
and the follow-up `prd.md` when one was emitted.

Rules

• Status stays Draft until the people involved have reviewed it — a postmortem nobody involved has read is one narrative, not a record.
• No names in causal positions. People may appear in the timeline as actors (“responder”, or a name for factual actions); no factor or action item may locate the problem in a person.
• Every factor ties to at least one action item or an explicit “accepted risk” note — an analyzed factor with no disposition is a loose end.
• The companion prd.md (when systemic work is emitted) lives in the same plans/incident-<date>-<slug>/ folder and follows the standard PRD schema, with the postmortem’s action items as its labeled requirements — the same entry path into design-to-tasks the audit skills use.