write-a-postmortem
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.
Install / Use
npx skills add inkeep/open-knowledge --skill write-a-postmortemInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Content & MediaSupported Platforms
Our assessment of write-a-postmortem
write-a-postmortem scores 94/100 on our quality scale, 157th of 1,155 Content & Media skills we index (top 14%).
Its SKILL.md is 17 KB long, well organised into 14 sections with 3 code examples: a thorough specification that gives an agent plenty to work with.
With 4,309 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 2 months ago, so write-a-postmortem is actively maintained.
- Our last check on 2026-11-16 found the source still online.
- It is released under GPL-3.0, a copyleft license: you can use it, but modified versions you distribute must carry the same license.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-09-29. Automated pattern scan on 2026-09-29. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
write-a-postmortem compared with similar skills
All 4 of these similar skills score higher than write-a-postmortem; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| write-a-postmortem (this skill)by inkeep | 94 | 4.3k | 53d ago | SKILL.md |
| siyuanby siyuan-note | 100 | 47.3k | today | MCP Server |
| x402by browser-use | 100 | 121.0k | 3d ago | SKILL.md |
| algorithmic-artby anthropics | 100 | 177.9k | 55d ago | SKILL.md |
| pptxby anthropics | 100 | 177.9k | 55d ago | SKILL.md |
Frequently asked questions
- How do I install write-a-postmortem?
- Run
npx skills add inkeep/open-knowledge --skill write-a-postmortem. The install tabs above show the steps for each supported agent. - Which AI agents does write-a-postmortem work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is write-a-postmortem safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is GPL-3.0-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is write-a-postmortem still maintained?
- The repository was last updated about 2 months ago, so write-a-postmortem is actively maintained.
Skill content
View source on GitHubname: write-a-postmortem
description: "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."
compatibility: "Any agent host with the OpenKnowledge MCP server configured. Installed project-local by ok seed --pack software-lifecycle."
metadata:
pack: "software-lifecycle"
author: "Inkeep"
repository: "https://github.com/inkeep/open-knowledge-skills"
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.
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.
Step 3 — Create the postmortem from the template
write({ document: { path: "postmortems/YYYY-MM-DD-name.md", template: "postmortem" } })
- The date is the incident date, not today's. If the outage was 2024-03-02, the filename is
postmortems/2024-03-02-name.mdeven if you write it a week later. nameis a short kebab slug of the affected system and failure:payments-pool-exhaustion,auth-cert-expiry,search-index-corruption.- The
postmortemtemplate 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.
Step 4 — Summary: impact first, cause second
The Summary is read by people who will never read the rest. Write it for the org, not for the on-call engineer.
- Lead with user-visible impact: who was affected, how, and for how long. "For 47 minutes, roughly 12% of checkout attempts failed with a 500." Not "the connection pool saturated."
- Then one sentence of cause, plain: "A config change halved the pool size while traffic was at peak; the pool exhausted and requests queued past timeout."
- If Step 2 found a repeat class, it goes here (see Step 2).
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.
Step 5 — Timeline: timestamped, sourced, with the detection gap made explicit
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)
- Call out detection time and mitigation time explicitly. Mark the entry where the incident began, where it was detected, and where it was mitigated.
- The gap between incident start and detection is usually the most actionable number in the document. Here: onset 14:03, first page 14:19 — sixteen minutes blind. Name that gap in prose right after the timeline: "Detection lagged onset by 16 minutes; there was no alert on checkout error rate, only on host CPU." That sentence is often the source of the highest-leverage action item.
- Keep entries factual and sourced. Analysis goes in Root cause, not here.
Step 6 — Trigger vs root cause vs symptom
Give the reader the three definitions, then separate them cleanly. Conflating them is the most common way a postmortem produces a shallow fix.
- Symptom — what was observed. "Checkout requests returned 500s; the pool showed zero free connections." The symptom is real but it is not the cause; fixing the symptom (restart, scale up) ends the incident without preventing the next one.
- Trigger — the specific thing that set it off. "Config change #4821 halved the pool size at peak traffic." The trigger is necessary to the story but rarely the whole cause.
- Root cause — the condition that made the trigger sufficient to cause the outage. Not "a bad config was pushed" — ask what made a bad config pushable to production at peak with no guard. The root cause is usually a missing safeguard, not the triggering action.
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.
Step 7 — Contributing factors
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:
- Missing or misrouted alerts — the detection gap from Step 5 almost always lands here.
- Absent or stale runbook — no documented recovery path, so the on-call improvised. Check
guides/and itslast_verifieddates. - Unclear ownership — nobody knew who owned the failing component, so acknowledgement lagged.
- A stale guide — a runbook th
Truncated for display — read the full file on GitHub.
Related Skills
siyuan
47.3kAn open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间,让人与智能体在此协作
x402
121.0kSet up Browser Use Cloud payments with x402 — pay per request from a crypto wallet (USDC on Base mainnet), no signup or API key.
algorithmic-art
177.9kCreating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems.
pptx
177.9kUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an em…
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
