From raw chat to committed report in 60 minutes. Nine stages. One funnel. AI as facilitator, never sole author. Names never reach the root cause.
Postmortems fail in three ways. They get skipped because writing them hurts. They stop at "human error" and miss the systemic cause. And the action items rot in a doc nobody opens again.
Why-Postmortem is a Claude Code skill wrapped in a guided web flow. Nine stages, one incident at a time. AI plays the facilitator — proposes timelines, challenges weak whys, drafts the report — but it never authors anything alone. Every stage has an accept / reject / edit gate.
The blameless guardrail is non-negotiable. The 5-Whys stage intercepts answers that mention a person by name and forces a reframe to a role, a control, a process gap. Twice — once in the UI, once at the prompt layer. Defense in depth.
This is the backward-looking sibling of PM Copilot. Same machine, opposite end of the build–break–learn loop. PM Copilot stress-tests the spec before the work; Why-Postmortem stress-tests the system after the incident. They share an engine: context layer + AI-stress-tested funnel + structured artifact.
One important difference. PM Copilot's POC runs on localStorage. Why-Postmortem can't. It writes files to disk, validates against schemas, streams AI output through a typed-output layer (BAML), and round-trips with a CLI skill. Browser alone is not enough. The backend story is the second half of this manual.
Three ingredients, in this order. Context layer loaded once. A funnel that's hard to skip. A structured artifact at the end.
Generic prompts produce generic reports. Grounded prompts — fed your services catalog, your severity matrix, your team roster — produce reports a senior practitioner would recognise. That grounding is the context layer, and it lives in git, not in the app.
| Layer | PM Copilot | Why-Postmortem |
|---|---|---|
| Time direction | Forward — define the right product | Backward — learn from the incident |
| Context | Personas, triggers, success-metric rules | org · services · teams · severity · enums · glossary · history |
| Funnel | Why → Personas → Edges → SMART → Trace | Timeline → Fishbone → 5-Whys → Draft → Actions |
| Stress test | Recursive whys on problem statement | 5-Whys per fishbone branch (parallel) |
| Hard guardrail | SMART validation | Blameless name-scrub (UI + prompt) |
| Output | BRD / PRD markdown | Postmortem folder + metadata.yaml |
The most important stage. Generic prompts produce generic reports. Grounded prompts produce something a senior practitioner would recognise.
What this stage does: reads seven files from _context/. Validates them against schemas. Lists missing required keys as TODOs. Surfaces counts (X services, Y teams, Z severity bands). Never overwrites filled values silently.
/postmortem:init scaffolds _context/ with template files.org.yaml lists SOC2/PCI/HIPAA → drafter auto-adds Compliance Impact subsection.Company name · domain · compliance regimes · ticket system · on-call tool · business hours.
Service catalog: name · owner team · tier · SLOs · dependencies · runbook link.
Team roster: name · Slack channel · on-call rotation · lead · escalation path.
SEV1–4 thresholds: users impacted · revenue/hr · SLO breach · compliance trigger.
Allowed values: root_cause_category · contributing_factors · tags. The vocabulary.
Internal terms · acronyms · system codenames so AI doesn't expand "TRP" wrong.
Known recurring issues. Prior root causes. "Don't re-discover" list.
Pointers to per-service runbooks. Linked from timeline mitigation steps.
Slug + date form the folder name. Severity is auto-suggested from the matrix once you enter impact fields. Services autocomplete from your catalog. Roles, not names.
Then drop the artifacts. Slack export. PagerDuty payload. Deploy log. Screenshots. Drag-drop into the raw box; files stored as raw/ matching the skill's folder layout exactly. 10 MB per file, 50 MB total per incident.
YYYY-MM-DD-<slug>.severity-matrix.yaml; user overrides with reason.services.yaml.# entered impact users_impacted: 7,500 tier_0_service_degraded: true duration_minutes: 75 # matched against severity-matrix.yaml → suggested: SEV2 matched_rule: "users_impacted 1000-10000 OR tier_0_service_degraded" override: null
Two-pane working surface. Raw materials on the left. AI-generated chronology on the right, streaming. Inline edits stick. Re-runs preserve human edits.
What the AI does: reads your raw drop, builds a chronology in markdown. Highlights decision points. Flags any window ≥ 10 min of inactivity during the active incident — those are gaps the team will want to explain.
business_hours_tz from org.yaml.runbooks/ when possible.## Timeline (America/New_York) - 14:02 · Deploy SHA `a1f3b2c` to checkout (tier-0). On-call SRE confirms green. - 14:09 · Synthetic monitor `/api/checkout` → p99 latency climbs from 180ms → 1.2s. - 14:11 · PagerDuty fires SEV2. On-call SRE acks. - 14:14 · 5xx rate on checkout reaches 4.3%. Customer support tickets begin queueing. - 14:26 · [GAP — 12 min] No action recorded. - 14:38 · Incident commander joins. Rollback initiated. - 15:17 · Deploy reverted. 5xx returns to baseline.
Six fixed columns. AI proposes 2–4 candidate causes per column with quoted evidence from the timeline. You accept, reject (with reason), or edit. Accepted causes become branches for the 5-Whys stage.
"No canary stage between green-light and 100% rollout."
evidence: timeline 14:02 → 14:09. maps to: change_mgmt_gap
"Synthetic monitor caught it but page took 2 min to fire."
evidence: 14:09 → 14:11. maps to: alert_latency
"12 min gap with no incident commander assigned."
evidence: 14:26 → 14:38. maps to: ic_handoff_unclear · recurrence flag from history.md
One thread per accepted fishbone branch. Conversational: you answer, AI challenges, AI asks the next "why". Lands on an enum-tagged systemic cause. Stops when systemic — not when the chain reaches five.
The blameless guardrail. Before your answer is submitted, the UI heuristic blocks any answer mentioning a person by name, an @mention, or a known roster name from teams.yaml. Prompts you to reframe to a role / system gap. Server-side prompt re-checks. Defense in depth.
missing_periodic_review.The drafter auto-assembles the report from stages 03–05 using the skill's _template/report.md. Eight sections in canonical order. Streaming markdown, rendered preview, toggle to raw textarea.
Inline blameless audit. Runs a typed BAML check returning a list of violations: severity (HIGH/MED/LOW) · kind (name / blame-language / passive-voice gap) · location (line ranges) · original · suggested fix · why. Per-violation: apply suggested · mark fixed · override with reason. HIGH violations block save.
{
"violations": [
{
"severity": "HIGH",
"kind": "personal_name",
"location": { "section": "root_causes", "line": 4 },
"original": "Sarah forgot to update the escalation policy.",
"suggested": "The escalation policy was not reviewed after the on-call topology change.",
"why": "Names belong in the timeline by role only. Root cause must be systemic."
},
{
"severity": "MED",
"kind": "blame_language",
"original": "The team failed to...",
"suggested": "The process did not surface..."
}
]
}
Stage 07 parses the action items table from the draft's section 7. Each row becomes editable: ID · title · owner (role from teams.yaml) · due date (default by severity SLA) · what it addresses (enum from enums.yaml) · status.
Stage 08 exports the folder. Identical shape to a skill-authored postmortem. A CLI user can pull the export and continue with any /postmortem:* command — no migration needed.
status: closed, rebuilds postmortems/README.md index.postmortems/2026-05-08-checkout-5xx-fraud-redos/ ├── metadata.yaml # typed: severity, services, MTTR, root_cause enums ├── timeline.md # stage 03 output ├── fishbone.md # stage 04 output ├── whys.md # stage 05 — one section per accepted branch ├── report.md # stage 06 — blameless-audited ├── actions.json # stage 07 sidecar — ticket IDs once created └── raw/ ├── slack.txt ├── deploy.log └── pagerduty.json
/postmortem:blameless-check on the exported folder returns clean. README.md index regenerated. Status closed.PM Copilot ships as a forward-looking spec tool. localStorage holds the doc. No server-side state, no file writes, no schema validation against a vocabulary. Why-Postmortem is different in six ways. Each one drags it out of the browser.
Output round-trips with the CLI skill — exact folder shape, multiple files (report.md, timeline.md, fishbone.md, whys.md, metadata.yaml, raw/*). Browser file APIs can't write folders to arbitrary paths.
Single source of truth = _prompts/*.md in the skill repo. Backend reads them at runtime, substitutes {{slug}} + {{tz}}, appends incident artifacts + context, passes to BAML. Re-hardcoding them client-side guarantees drift.
Stage 05 needs WhysTurn (NEXT_WHY / REFRAME / SYSTEMIC / TOO_DEEP). Stage 06 needs BlamelessAuditResult (typed violations). BAML generates a typed client + validator; runs server-side. No browser equivalent without exposing keys.
enums.yaml.Every root cause + contributing factor must match an allowed enum. metadata.yaml must validate against the skill's schema before save. Validation logic lives once on the server; not duplicated and de-synced in the SPA.
UI heuristic blocks names client-side. Prompt re-checks server-side. If the UI is bypassed (devtools, paste, copy-edit), the prompt layer still intercepts. The audit re-runs server-side on save. Two layers — neither is optional.
Default provider = OpenAI. Swap to Anthropic by editing one BAML client file + npm run baml:generate. No frontend change. API keys live in .env, never in the browser. Keys + provider routing belong on the server.
:5173 dev server/api/* → :3001fetch → reader → render_context/ at every call_prompts/*.md from skill repoGenerate(prompt) for free-form markdownWhysTurn typed for stage 05BlamelessAuditResult typed for stage 06.env| Method | Path | Purpose |
|---|---|---|
| GET | /api/health | Liveness |
| POST | /api/context/validate | Read + validate _context/ |
| POST | /api/context/data | Parsed services / teams / severity / enums |
| POST | /api/severity/suggest | Match impact inputs against matrix |
| POST | /api/incident/create | Write metadata.yaml skeleton + folder |
| POST | /api/incident/raw | Write raw/ files (utf8 / base64) |
| GET | /api/incident/files | List incident folder for export view |
| POST | /api/timeline/generate | Streaming markdown |
| POST | /api/timeline/save | Write timeline.md |
| POST | /api/fishbone/generate | Streaming markdown |
| POST | /api/fishbone/save | Write fishbone.md |
| POST | /api/whys/next | Typed WhysTurn per round |
| POST | /api/whys/save | Write whys.md |
| POST | /api/draft/generate | Streaming full report |
| POST | /api/draft/save | Write report.md |
| POST | /api/blameless/check | Typed BlamelessAuditResult |
| POST | /api/actions/parse | Extract table from report § 7 |
| POST | /api/actions/save | Sidecar + metadata patch + report refresh |
| POST | /api/export/finalize | Status closed · rebuild README index |
The webapp is local-only by design. The author runs npm run dev on a laptop. Hosting the full POC needs more than a static CDN. But not everything is dynamic.
why-postmortem-magazine.htmlone-pager.html · printableinfographic.html · POC overviewdeck.html · pitch slidesdemo-video.html + .mp4brd-*.md rendered via any static MD hostwebapp/ — Vite SPA needs paired backendwebapp/server/ — Express on :3001raw/, report.md, etc.)_context/ file readsShip the magazine + landing pages to CF Pages. Keep webapp/ local. Demo via screencast.
Cost: free · risk: none · gets the story out today.
Convert Express routes to functions/api/*.ts. Use R2 for raw artifacts. KV for context cache. BAML calls via Worker secrets.
Cost: ~free at POC scale · risk: rewrite + cold starts.
SPA on CF Pages. Express on Fly.io or Render with a persistent volume for incident folders. BAML server-side.
Cost: $5/mo · risk: lowest, matches local-dev shape exactly.
# prep folder mkdir dist-why-postmortem cp why-postmortem-magazine.html dist-why-postmortem/index.html cp one-pager.html infographic.html deck.html demo-video.html dist-why-postmortem/ cp demo-video.mp4 favicon.svg why-postmortem.png dist-why-postmortem/ # deploy npx wrangler@latest pages deploy dist-why-postmortem \ --project-name why-postmortem-checks \ --branch main # → https://why-postmortem-checks.pages.dev
This manual mirrors the why-postmortem webapp POC at webapp/ — same nine stages, same skill commands, same context layer, same blameless guardrail. Built in the dark-canvas brand from brand-kit.md, paired with the forward-looking PM Copilot manual at pdm-magazine.html.
The story is shippable to CF Pages today. The webapp is local-only by design — see page 23 for the six structural reasons. When the runtime is ready, paths B and C on page 29 are waiting.
brand-kit.mdpdm-magazine.html