write-a-postmortem

# Write a postmortem

The platform `/open-knowledge` skill still governs every markdown operation here — folder scope, the read/write tool surface, linking, and preview. This skill layers postmortem craft on top of it; it does not replace those rules.

A postmortem is not a status update and not a blame ledger. It is a durable, blameless reconstruction of one incident, built from evidence, that makes the system's failure mode legible and produces action items someone will actually verify. The value compounds only when postmortems that share a subsystem link to each other — that is how a repeat class stops being invisible.

This pack scaffolds `proposals/`, `decisions/`, `specs/`, `postmortems/`, and `guides/` at the project root. Postmortems live in `postmortems/`, one file per incident, filename `YYYY-MM-DD-name.md`, template id `postmortem`. Action items that are guide-shaped produce `runbook` stubs in `guides/`.

The knowledge base is markdown owned by OpenKnowledge MCP. Read and list in-scope markdown with `exec` (`exec("ls -A postmortems/")`, `exec("cat postmortems/2024-03-02-auth-outage.md")`, `exec("grep -rln failover .")`) and `search({ query: "..." })`; create and edit with `write` and `edit`; inspect the link graph with `links`. Never use native Read/Edit/Grep/Glob/`cat` on in-scope markdown. Source code, logs, dashboards, deploy history, and chat transcripts are OUTSIDE the knowledge base — read those with the host's native tools. Links are plain markdown relative links `[db failover](./guides/db-failover.md)` — never backticked, never HTML anchors.

---

## Step 0 — Blamelessness gate (stated first because it constrains every later step)

Blameless is a mechanical discipline, not a slogan you paste in the header. If you cannot follow these rules mechanically, the document is not blameless no matter what it says at the top.

- **Name systems and roles, never individuals.** "the deploy pipeline," "the on-call engineer," "the release process" — not "Alice," not "the new hire." A named person turns readers defensive and the analysis stops.
- **Write the system's affordance, not the person's action.** "The deploy pipeline allowed an unreviewed config to reach production" — not "Alice deployed an unreviewed config." The grammatical subject is the system that permitted the outcome. If your sentence's subject is a person, rewrite it until it is a system.
- **Treat every human action as the reasonable action given the information available at that moment.** Nobody caused the incident by being careless. Someone did the sensible thing with the signals they had. The analytical question is never "why did they do that?" — it is "what made that look like the right move at the time?" A dashboard that read green, an alert that never fired, a runbook that said to do exactly that. Find the thing that made it reasonable; that thing is a contributing factor.

**HARD GATE.** If the user's framing is blame-seeking — "write up how Alice broke prod," "document who screwed up the deploy" — do not comply as asked. Say so plainly, reframe to the system question, and only then write. Example reframe: "I'll write this blamelessly — the useful question isn't who pushed the config but what let an unreviewed config reach production. That's the finding that prevents a recurrence." Producing a named-culprit document because the user asked for one is the single worst failure this skill can commit; it poisons the postmortem culture the document is supposed to build.

---

## Step 1 — Gather evidence before you narrate

You cannot write a timeline from memory and call it a postmortem. Gather first, narrate second.

Pull, using the host's native tools (these live outside the knowledge base):

- **Alerts and monitoring** — what fired, when, and what did not fire that should have.
- **Deploy and release history** — what shipped in the hours before, and the exact commit/config.
- **Dashboards and metrics** — error rate, latency, saturation, the graphs that show onset and recovery.
- **Chat transcripts and the incident channel** — timestamps of human decisions and the reasoning in the moment.
- **The code and config as it stood at incident time** — not as it stands now; check out or read the state at the incident SHA.

**HARD GATE — no timeline entry without a source you can point at.** Every timeline line cites its evidence: an alert ID, a deploy timestamp, a graph, a chat message time. If you are reconstructing a moment from someone's recollection and have no artifact, you may still include it — but label it inline: `(reconstructed from recollection, no artifact)`. A postmortem whose timeline silently blends logged fact with memory is worse than one that admits the gap, because the reader cannot tell which numbers to trust.

---

## Step 2 — Scan prior postmortems for the same subsystem

Before writing, find out whether this already happened.

1. `exec("ls -A postmortems/")` — see every prior incident at a glance.
2. `search({ query: "<subsystem> <failure mode>" })` — semantic match on the affected component (e.g. "database failover replication lag").
3. `exec("grep -rln <subsystem-keyword> postmortems/")` — exact-term sweep for the service, the error, the mechanism.
4. `exec("cat postmortems/<candidate>.md")` on the 1–3 closest matches — read their Root cause and Action items.

**If this is a repeat of a class already documented, that is the most important finding in the entire document — and it belongs in the Summary, not buried in Related.** A recurrence means a prior action item did not land, or landed and did not prevent recurrence. State it in the first two sentences: "This is the third connection-pool exhaustion incident in the payments service (see [2024-01-11](./postmortems/2024-01-11-payments-pool.md), [2024-03-02](./postmortems/2024-03-02-payments-pool.md)); the action item from the second was never completed." Repeat classes are where postmortems earn their keep — surface them loudly.

---

## Step 3 —