writing-postmortems
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseWriting postmortems
撰写 Postmortem 文档
REQUIRED BACKGROUND: the skill (hard rules, truth rules, style).
technical-writing必备背景知识： 技能（硬性规则、真实性规则、风格规则）。
technical-writingOverview
概述
A postmortem is written for the engineer who hits something similar in a year, not for the people in the room. Core principle: facts from evidence, causes from mechanisms, lessons from both, and no names. The document is historical by classification: once reviewed, it is immutable, and corrections are dated addenda.
Postmortem 文档是为一年后遇到类似问题的工程师撰写的，而非针对当时在场的人员。核心原则：基于证据的事实、基于机制的原因、从两者中总结经验教训，且不提及具体人名。该文档属于历史记录类：一经审核，便不可更改，如需修正需添加带日期的附录。
When to invoke, and not
适用场景与禁用场景
Invoke after an incident is resolved (or at a stable milestone of a long one), after a defect that reached users, and after a near miss: a guard that caught what review missed is the cheapest lesson available and earns the same write-up. Do NOT invoke during the live incident (the runbook governs that), for assigning accountability (a postmortem that needs a person's name to make sense is describing a process hole), or for a status update to stakeholders (that is a report, not a postmortem).
在事故解决后（或长期事故的某个稳定里程碑后）、影响用户的缺陷发生后、未遂事件发生后适用本技能：防护机制拦截了评审未发现的问题，这是成本最低的经验教训，同样需要撰写文档。请勿在事故处理过程中使用（此时应遵循运行手册）、请勿用于问责（若一份Postmortem文档需要提及人名才有意义，说明存在流程漏洞）、请勿用于向利益相关者提供状态更新（这属于报告，而非Postmortem文档）。
Skeleton
文档框架
markdown
undefinedmarkdown
undefined[System]: [the failure, as its symptom, one line]
[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 |
| Incident date | YYYY-MM-DD |
| Duration | detection to resolution |
| Severity | [per the org taxonomy, defined where used] |
| Status | Draft / Reviewed |
Summary
Summary
[User-visible impact with numbers, the root cause in one sentence, current state.
The reader who stops here still knows what happened.]
[User-visible impact with numbers, the root cause in one sentence, current state.
The reader who stops here still knows what happened.]
Impact
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.]
[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
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.]
[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
Root cause and contributing factors
[The mechanism, grounded in code and commits. Contributing factors as a list:
real incidents rarely have one cause, and "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.]
[The mechanism, grounded in code and commits. Contributing factors as a list:
real incidents rarely have one cause, and "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.]
What we got wrong during response
What we got wrong during response
[The wrong first fix, the misleading signal followed, the theory that cost an hour.
Recording the plausible-but-wrong path is what saves the next responder from it.]
[The wrong first fix, the misleading signal followed, the theory that cost an hour.
Recording the plausible-but-wrong path is what saves the next responder from it.]
Action items
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.]
undefined[Each with an owner and an acceptance check, filed as tracker issues and linked.
"Investigate X" without an owner is banned here as everywhere.]
undefinedRules
规则
- Blameless means structural. Name the role, the gate, the dependency, the missing guard; never the person. This is not politeness: a postmortem blaming a person stops at "be more careful", and one blaming a structure produces an action item. The rule 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 and is defined where used, not assumed. No taxonomy available: leave the field explicitly unassigned rather than inventing one.
- Action items follow : 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
writing-issues; the postmortem stays Draft until the links exist.[to file: <who files it>] - 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 in the core skill).
references/truth.md - 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 and linked, not embedded. The runbook updates the incident exposed go through in the same change, per the docs-update-with-the-change rule.
recording-decisionswriting-runbooks- 无责意味着针对流程：提及角色、关卡、依赖项、缺失的防护机制；绝不提及具体个人。这并非出于礼貌：指责个人的Postmortem文档只会停留在“要更谨慎”的层面，而针对流程的文档则会产生可执行的行动项。本规则适用于叙述部分（时间线、原因、响应过程）；行动项的责任人是任务分配，而非指责：文档中提及角色，而关联的跟踪工单中提及具体个人。
- 时间线是证据，而非叙事：每一条记录都可追溯至可验证的依据：警报、日志行、提交记录、消息。解读内容应放在以下章节，绝不能出现在时间线中。若只能依靠记忆作为来源，需明确说明。
- 错误的修复方案也是内容：看似合理但无效的修复方案及其背后的推理过程都应纳入文档；尴尬不能成为不记录的理由。
- 严重程度遵循组织分类标准：使用时需明确定义，而非主观假设。若无可用分类标准：需明确留空该字段，而非自行创建。
- 行动项遵循 规范：包含预期结果、责任人、验收标准，已提交至跟踪系统并关联链接，绝不能仅以文字描述的形式留在Postmortem文档中。若无法从当前位置提交，需标记每个行动项为
writing-issues；在链接生成前，Postmortem文档保持“草稿”状态。[待提交: <提交人>] - 一经审核，不可更改：新发现需添加带日期的附录；重写Postmortem文档属于伪造记录。审核过程本身需记录在签署行中（详见核心技能中的 ）。
references/truth.md - 未遂事件使用相同框架：影响部分需描述可能发生的情况，并明确标注为假设场景。
Postmortem文档之后通常会做出的决策（如新的约束条件、政策变更）需通过 技能记录并关联，而非嵌入文档中。事故暴露的运行手册更新需同步通过 技能完成，遵循“随变更更新文档”的规则。
recording-decisionswriting-runbooks