Loading
Write a blameless incident postmortem under postmortems/ following the Google SRE shape — evidence-based timeline, trigger vs root cause vs symptom, contributing factors, what went well, and owned+dat
The skill file stays in the publisher's repository.
Paste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add inkeep/open-knowledge --skill write-a-postmortem -a cursor -y
Write a blameless incident postmortem under postmortems/ following the Google SRE shape — evidence-based timeline, trigger vs root cause vs symptom, contributing factors, what went well, and owned+dated+verifiable action items. Read when asked to write a postmortem, do an incident review, run a root cause analysis, write up the outage, retro on the outage, or when the user says we had an incident and wants it documented. Do NOT read to frame a proposal (use frame-a-proposal), write a spec (use write-a-spec), record a decision (use record-a-decision), or review a design (use review-a-design) — a postmortem documents an incident that already happened, it does not propose, specify, decide, or critique future work.
Write a blameless incident postmortem under postmortems/ following the Google SRE shape — evidence-based timeline, trigger vs root cause vs symptom, contributing factors, what went well, and owned+dated+verifiable action items. Read when asked to write a postmortem, do an incident review, run a root cause analysis, write up the outage, retro on the outage, or when the user says we had an incident and wants it documented. Do NOT read to frame a proposal (use frame-a-proposal), write a spec (use write-a-spec), record a decision (use record-a-decision), or review a design (use review-a-design) — a postmortem documents an incident that already happened, it does not propose, specify, decide, or critique future work.
ok seed --pack software-lifecycle (ok-beta for Beta)."
metadata:
pack: "software-lifecycle"
author: "Inkeep"
repository: "https://github.com/inkeep/open-knowledge-skills"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.
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.
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.
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):
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.
Before writing, find out whether this already happened.
exec("ls -A postmortems/") — see every prior incident at a glance.search({ query: "<subsystem> <failure mode>" }) — semantic match on the affected component (e.g. "database failover replication lag").exec("grep -rln <subsystem-keyword> postmortems/") — exact-term sweep for the service, the error, the mechanism.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, 2024-03-02); the action item from the second was never completed." Repeat classes are where postmortems earn their keep — surface them loudly.
write({ document: { path: "postmortems/YYYY-MM-DD-name.md", template: "postmortem" } })
postmortems/2024-03-02-name.md even if you write it a week later.name is a short kebab slug of the affected system and failure: payments-pool-exhaustion, auth-cert-expiry, search-index-corruption.postmortem template scaffolds the SRE shape: Summary / Timeline / Root cause / What went well / Action items. Fill each in the steps below; do not invent a different structure.The Summary is read by people who will never read the rest. Write it for the org, not for the on-call engineer.
A summary that leads with the technology ("the connection pool saturated at 14:03") and buries the impact is written for engineers, not for the organization that needs to weigh the incident. Impact is the currency; state it first and in human terms.
Reconstruct the incident chronologically. Every entry: a timestamp with time zone, what happened, and the evidence it came from.
- 13:52 UTC — Config change #4821 merged, halving `pool.max` from 200 to 100. (deploy log, PR #4821)
- 14:03 UTC — Checkout error rate crosses 5%. (Grafana, checkout-errors panel)
- 14:19 UTC — First page fires to on-call. (PagerDuty incident #9917)
- 14:26 UTC — On-call acknowledges, begins investigating a suspected upstream issue. (incident channel)
- 14:41 UTC — Config change identified as cause; rollback initiated. (incident channel)
- 14:50 UTC — Error rate returns to baseline. (Grafana)
Give the reader the three definitions, then separate them cleanly. Conflating them is the most common way a postmortem produces a shallow fix.
Push past the first plausible cause. If your answer is "someone pushed a bad config," you have named the trigger and stopped. Keep going: What allowed an unreviewed config to reach production? Why was there no validation on pool-size bounds? Why did no canary catch it? Techniques like "five whys" help you keep asking — but they are a prompt, not a proof, and they tend to walk you down a single chain when reality had several. Most incidents have several contributing factors and one or two root causes, not a single linear chain. Name the one or two conditions that, if they had not held, the trigger would have been harmless.
The conditions that widened the blast radius, delayed detection, or slowed recovery. These are not the root cause but they are why the incident was as bad as it was — and each is usually its own action item.
Look specifically for:
guides/ and its last_verified dates.last_verified was long past.List each as a discrete factor. Vague "communication could have been better" is not a factor; "there was no owner mapping for the payments pool, so the first page went to the wrong team for 7 minutes" is.
This section is not filler and skipping it quietly is a failure mode. Something limited the damage; name it so the org preserves it.
Write it honestly. If genuinely little went well, say that plainly rather than manufacturing praise — "recovery was slow and manual; the one thing that worked was that rollback was a single command." Preserving what worked is as much the point as fixing what didn't.
An action item with no owner is a wish. Every item gets three things or it does not go in the list:
Classify each item by what it buys you:
A healthy postmortem has items across all three; a list that is all prevention often means the detection and mitigation gaps went unexamined.
Guide-shaped action items produce runbook stubs. When an item is "write/fix the recovery runbook for X," don't just name it — stub it now:
write({ document: { path: "guides/db-pool-exhaustion-runbook.md", template: "runbook" } })
Pre-fill the stub with the symptom (how you'd recognize this again — "checkout 500s + pool free-connections at zero") and the relevant timeline excerpt (the rollback steps that actually worked, lifted from Step 5). Then link the stub from the action item: - [ ] Payments team, by 2024-03-16: complete the [pool-exhaustion runbook](./guides/db-pool-exhaustion-runbook.md), verified by a tabletop dry-run. The runbook carries last_verified frontmatter so it surfaces in review when it goes stale.
## Related section linking every prior postmortem that shares a subsystem (from Step 2), plus the decisions/ and specs/ implicated — the decision that set the config policy, the spec for the component that failed. [2024-01-11 payments pool](./postmortems/2024-01-11-payments-pool.md), [connection-pool sizing decision](./decisions/2023-11-04-pool-sizing.md).## Related.INDEX.md in postmortems/) so the new incident shows up in the index — the preview becomes a live progress bar.audit({ path: "postmortems/YYYY-MM-DD-name.md" }) returns clean (every lint violation + broken internal link) — fix every finding. Confirm frontmatter is complete and the Summary / Timeline / Root cause / What went well / Action items sections are all filled, none left as template placeholder.Close in conversation with four things, tightly:
Then point at the file: postmortems/YYYY-MM-DD-name.md and any runbook stubs created.
/frame-a-proposal) or a design review (/review-a-design) — link to it from Related; don't fight it here.