writing-postmortems

撰写事后复盘

必备背景：technical-writing 技能（硬性规则、事实规则、风格）。

概述

受众：一年后遇到类似问题的工程师，而不是当时在场的人。核心原则：**依据证据陈述事实，根据机制分析原因，从两者中总结经验教训，不提及姓名。**分类：历史记录；审核后不可更改，修正内容以注明日期的补充说明记录。

何时调用，何时不调用

事件解决后，或长期事件达到稳定里程碑时调用。影响到用户的缺陷和险些酿成事故的事件（防护措施发现了评审遗漏的问题）都应撰写同样的复盘。不要在事件正在处理中调用：此时应遵循运行手册。不要用于追究责任：如果一份复盘必须提及某个人的姓名才能说清楚，那描述的就是流程漏洞。不要用于向利益相关方发布状态更新，那属于报告。

骨架

# [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.]

规则

• **无责复盘意味着着眼于结构。**指出角色、关卡、依赖项、缺失的防护措施；绝不指出个人。指责个人只会止步于“更加小心”；指责结构才能产生行动项。这适用于叙述内容（时间线、原因、响应）；行动项的负责人分配不属于指责：本文档中写角色，关联的跟踪器问题中写个人。
• **时间线是证据，不是叙述。**每条记录都要能追溯到可核查的信息，时间戳取自系统而非记忆。如果记忆是唯一来源，请明确说明。
• **错误的修复方案也属于内容。**看似合理却未奏效的修复方案，以及让它显得合理的推理过程，都应写入文档；尴尬不是保留记录的理由。
• 严重程度依据组织的分类体系，并在使用处定义，不要想当然。若没有分类体系，应明确将此字段标记为未分配，而不是自行编造。
• 行动项遵循 writing-issues：写明结果、负责人和验收检查，创建问题并附上链接，绝不能只把行动意图留在复盘文字中。如果无法在当前环境中创建问题，请将每项标记为 [to file: <who files it>]；在链接补齐前，复盘保持为 Draft。
• **审核后不可更改。**新发现以注明日期的补充说明记录；重写复盘等同于伪造记录。审核本身应写在签核行中（参见核心技能中的 references/truth.md）。
• 险些酿成事故的事件也使用同一骨架，在 Impact 中描述可能发生的后果，并标明这是反事实情形。

事后复盘之后常见的决策（例如新增不变量、变更政策）应通过 recording-decisions 记录并添加链接，不要直接嵌入复盘。更新运行手册应通过 writing-runbooks 完成，并与修复在同一变更中提交；文档工作属于完成事项的一部分，而不是后续工单。