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.