writing-postmortems
Use when writing a postmortem, incident report, or root-cause analysis after an outage, a defect that reached users, a data issue, or a near miss - or when turning an incident channel, alert log, or war-room thread into a durable document. Encodes the blameless framing, the evidence-only timeline, contributing factors, and owned action items. Use whenever something broke and the write-up must outlive the incident.
- Installs
- 18.4K
- Last 24h
- +418
- Trending rank
- #734
- Security
- Warn
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/riekelt/technical-writer --skill writing-postmortems- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads writing-postmortems automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
Security audits
Independent scans of the skill's instructions and bundled files.
SKILL.md
The instructions your agent reads when the skill is triggered.
Writing postmortems
REQUIRED BACKGROUND: the technical-writing skill (hard rules, truth rules, style).
Overview
Audience: the engineer who hits something similar in a year, not the people in the room. Core principle: facts from evidence, causes from mechanisms, lessons from both, and no names. Classification: historical; once reviewed it is immutable, and corrections are dated addenda.
When to invoke, and not
Invoke after an incident is resolved, or at a stable milestone of a long one. A defect that reached users and a near miss (a guard caught what review missed) earn the same write-up. Do NOT invoke during the live incident: the runbook governs that. Not for assigning accountability: a postmortem that needs a person's name to make sense is describing a process hole. Not for a status update to stakeholders, which is a report.
Skeleton
# [System]: [the failure, as its symptom, one line]
| | |
|---|---|
| **Incident date** | YYYY-MM-DD |
| **Duration** | detection to resolution |
| **Severity** | [per the org taxonomy, defined where used] |
| **Status** | Draft / Reviewed |
## Summary
[User-visible impact with numbers, the root cause in one sentence, current state.
The reader who stops here still knows what happened.]
## Impact
[Who and what, quantified: requests failed, records affected, money or time lost.
Estimates labeled as estimates; "no evidence of data loss" only if actually checked,
and say what was checked.]
## Timeline
[Timestamped entries, facts only, each traceable to evidence: an alert, a log line,
a commit, a message. Interpretation lives in the sections below, never here.]
## Root cause and contributing factors
[The mechanism, grounded in code and commits. Contributing factors as a list;
"every component was correct and the defect lived between them" is a valid root
cause. Name which layer of checking missed it and which caught it.]
## Wrong turns during the response
[The wrong first fix, the misleading signal followed, the theory that cost an hour.]
## Action items
[Each with an owner and an acceptance check, filed as tracker issues and linked.
"Investigate X" without an owner is banned here as everywhere.]
## Sign-off
[- YYYY-MM-DD <reviewer>: approved <scope>, one line per review event.]
Rules
- Blameless means structural. Name the role, the gate, the dependency, the missing guard; never the person. Blaming a person stops at "be more careful"; blaming a structure produces an action item. This governs the narrative (timeline, causes, response); action-item ownership is assignment, not blame: a role in this document, an individual in the linked tracker issue.
- The timeline is evidence, not narrative. Every entry traces to something checkable, timestamps from the systems rather than memory. Where memory is the only source, say so.
- Wrong fixes are content. The fix that made sense and did not work belongs in the document with the reasoning that made it plausible; embarrassment is not a retention policy.
- Severity comes from the org taxonomy, defined where used, not assumed. When no taxonomy exists, leave the field explicitly unassigned rather than inventing one.
- Action items follow
writing-issues: outcome, owner, acceptance check, filed and linked, never left as prose intentions in the postmortem. When filing is not possible from where you sit, mark each item[to file: <who files it>]; the postmortem stays Draft until the links exist. - Immutable once reviewed. New findings are dated addenda; a rewritten postmortem is a falsified record. The review itself goes in a sign-off line (see
references/truth.mdin the core skill). - Near misses use the same skeleton, with Impact describing what would have happened, labeled as the counterfactual it is.
The decision that often follows a postmortem (a new invariant, a policy change) is recorded via recording-decisions and linked, not embedded. Runbook updates the incident exposed go through writing-runbooks in the same change as the fix; documentation is part of done, not a follow-up ticket.
FAQ
What does the writing-postmortems skill do?
Use when writing a postmortem, incident report, or root-cause analysis after an outage, a defect that reached users, a data issue, or a near miss - or when turning an incident channel, alert log, or war-room thread into a durable document. Encodes the blameless framing, the evidence-only timeline, contributing factors, and owned action items. Use whenever something broke and the write-up must outlive the incident.
How do I install writing-postmortems?
Run npx skills add https://github.com/riekelt/technical-writer --skill writing-postmortems in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/writing-postmortems/ (personal) or .claude/skills/writing-postmortems/ (project).
Which AI agents can use writing-postmortems?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is writing-postmortems safe to install?
Security partners have reviewed it: Gen Agent Trust Hub passed; Socket passed; Snyk flagged items to review. As with any skill, read the SKILL.md and bundled scripts before installing.
Who maintains writing-postmortems?
It is published by riekelt in riekelt/technical-writer. It has 18,376 recorded installs.
More from riekelt/technical-writer
technical-writing
riekelt/technical-writer
Use when writing, restructuring, or revising any technical document - specs, design docs, READMEs, reference documentation, plans, reports - or any prose that must survive being read twice by someone in a hurry. Encodes the house style, the truth and sourcing rules, and the banned-constructions list. Use whenever you produce repository-bound text longer than a paragraph, even if nobody says "document". Foundation for the sibling document-type skills.
reviewing-technical-prose
riekelt/technical-writer
Use when reviewing, rewriting, or editing someone else's technical text, when writing a review report on a document, or as the final check before delivering any document. Encodes the severity mapping, the findings format, the what-not-to-flag list, and the delivery checklist. Use before any document ships, even when it looks fine.
writing-design-docs
riekelt/technical-writer
Use when writing a proposal, RFC, design document, spec, or migration plan - anything that argues for a change, records a design, or asks readers for input on one. Encodes the proposal skeleton, the Why & What decision box, and the completeness checks. Use whenever a change needs arguing or scoping in writing, even if the user just says "write up the approach".
writing-runbooks
riekelt/technical-writer
Use when writing operational documentation - runbooks, setup guides, release procedures, migration guides, deprecation guides, troubleshooting entries, or any ordered procedure someone will execute under time pressure. Encodes the runbook skeleton, the risk legend, the symptom-first troubleshooting format, and the migration-guide rules (mapping table, mandatory rollback, deprecation dates, built-in expiry). Use whenever someone will execute the text, even if it is called a "guide" or "setup notes".
writing-changelogs
riekelt/technical-writer
Use when writing a changelog entry, release notes, or a "what shipped" summary after completing work. Encodes the entry shape, the handover template, and the honesty conventions. Use after shipping meaningful work, even if the user just says "summarize what we did".
recording-decisions
riekelt/technical-writer
Use when a decision needs recording - an ADR, a decision log entry, or when someone asks to write down why something was chosen, rejected, or superseded. Encodes the ADR and decision-log formats. Use whenever a choice was made that would otherwise live only in chat, even if nobody says "ADR".
Popular docs & writing skills
grill-with-docs
mattpocock/skills
A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go.
lark-markdown
open.feishu.cn
飞书 Markdown：查看、创建、上传、编辑和比较飞书中的原生 Markdown 文件。当用户要操作飞书 Markdown 文件，或比较其远端版本及本地草稿时使用。纯本地 Markdown 文件操作不触发本 skill。不负责将 Markdown 导入为飞书在线文档，也不负责文件搜索、权限、评论、移动、删除等云空间管理操作。
writing-beats
mattpocock/skills
Writing, exploit; assemble raw material into a journey of beats, grounding each term before a beat leans on it.
writing-shape
mattpocock/skills
Writing, exploit: shape raw material into an article, paragraph by paragraph.
writing-fragments
mattpocock/skills
Writing, explore: mine raw fragments, no structure yet.
writing-for-agents
mattpocock/skills
Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.