| name | incident-retrospective |
| description | 线上事故复盘与结构化 Blameless Postmortem 撰写工具，遵循 SRE 最佳实践。帮助用户撰写专业的事故复盘报告，通过六步 SOP 引导完成从时间线梳理、5 Whys 根因分析到制定 SMART 改进措施的全过程，输出格式化的复盘文档。当用户需要撰写事故复盘、进行根因分析（RCA）、创建 blameless postmortem、分析线上故障、制定改进措施（action items）或总结事故教训时触发，常见于提到 postmortem、事故复盘、故障分析、RCA、5 Whys、incident review、故障报告等关键词的场景。 |
| license | MIT |
postmortem-writer
基于 Google SRE 和行业最佳实践的 Blameless Postmortem 撰写流程。通过结构化的 SOP 引导你完成从事故信息收集、时间线梳理、5 Whys 根因分析到改进措施制定的完整复盘过程，输出专业的事故复盘文档。
核心理念：Blameless（无责文化） — 关注系统和流程的改进，而不是追责个人。
Quick Start
交互式复盘（推荐）：直接描述你的事故情况，Agent 将按照 SOP 流程引导你逐步完成复盘。
一键生成文档：如果你已经有完整的事故信息，可以用脚本快速生成格式化的复盘文档：
python3 scripts/generate_postmortem.py --interactive
或提供 JSON 输入直接生成：
python3 scripts/generate_postmortem.py --input incident.json --output postmortem.md
SOP 流程：六步完成专业复盘
第一步：事故概况收集
收集以下基本信息，构建事故全貌：
| 字段 | 说明 | 示例 |
|---|
| 事故标题 | 简明描述故障现象 | 支付服务 P99 延迟飙升至 30s |
| 严重等级 | P0 ~ P3（见下方分级标准） | P1 |
| 影响开始时间 | 用户首次受影响的时间 | 2024-03-15 14:32 UTC+8 |
| 影响结束时间 | 故障完全恢复的时间 | 2024-03-15 16:45 UTC+8 |
| 持续时长 | 自动计算或手动填写 | 2h13m |
| 影响范围 | 受影响的用户/服务/区域 | 华东区 ~30% 用户支付失败 |
| 值班人 / 响应团队 | 参与处理的关键人员 | SRE on-call: 张三, 支付团队: 李四 |
严重等级分级标准：
| 等级 | 定义 | 典型场景 |
|---|
| P0 | 全站/核心业务不可用，影响大量用户 | 主站宕机、数据库集群故障、支付系统全面瘫痪 |
| P1 | 核心功能严重降级，影响显著比例用户 | 搜索不可用、下单成功率下降50%、API 错误率 > 10% |
| P2 | 非核心功能受损，或核心功能轻微降级 | 推荐系统延迟升高、个别区域服务异常、后台管理页面不可用 |
| P3 | 轻微问题，用户基本无感知 | 日志采集延迟、内部监控页面异常、非关键定时任务失败 |
第二步：时间线梳理
按时间顺序记录事故全过程，精确到分钟。每个事件需标注类别：
| 类别标签 | 说明 |
|---|
| TRIGGER | 触发故障的事件 |
| DETECT | 发现/告警事件 |
| ACTION | 采取的应对操作 |
| RESOLVE | 恢复/修复事件 |
| INFO | 其他信息性事件 |
时间线示例：
14:25 ACTION 部署 payment-service v2.3.1 到生产环境
14:32 TRIGGER 支付成功率从 99.8% 开始下降
14:35 DETECT 监控告警：支付成功率 < 95%
14:38 DETECT 客服接到用户反馈支付失败
14:42 ACTION 值班 SRE 开始排查，定位到 payment-service
14:55 ACTION 尝试重启 payment-service pod（无效）
15:10 ACTION 分析日志发现数据库连接池耗尽
15:25 ACTION 回滚 payment-service 到 v2.3.0
15:30 RESOLVE 支付成功率恢复至 99.5%
16:45 RESOLVE 积压订单全部处理完毕，确认完全恢复
关键度量指标（梳理时间线时同步记录）：
- TTD (Time to Detect)：从故障发生到被发现的时间
- TTR (Time to Resolve)：从故障发现到恢复的时间
- TTN (Time to Notify)：从故障发现到通知相关方的时间
- 影响用户数 / 影响请求数 / 经济损失估算
第三步：5 Whys 根因分析
5 Whys 是一种通过反复追问"为什么"来穿透表面原因、找到根本原因的分析方法。
执行规则：
- 从直接原因开始，每次追问"为什么会发生这个？"
- 至少问 5 层，直到触及可改进的系统/流程层面
- 每一层的回答必须基于事实和证据，不是猜测
- 如果一个"为什么"有多个原因，分支展开分别分析
- 最终的根因应该指向系统或流程缺陷，而不是某个人的失误
分析示例：
现象：支付服务 P99 延迟飙升至 30s
Why 1: 为什么延迟飙升？
数据库连接池被耗尽，请求排队等待连接
Why 2: 为什么连接池被耗尽？
新版本引入了一个未关闭数据库连接的 bug
Why 3: 为什么这个 bug 没在上线前被发现？
单元测试没有覆盖数据库连接释放的场景
Why 4: 为什么没有这类测试？
没有针对资源泄漏的测试规范和 checklist
Why 5: 为什么没有这个规范？
团队缺少针对资源管理的 code review checklist 和自动化检测
根因：缺少资源泄漏（连接池/文件句柄等）的自动化检测机制和 code review 规范
常见根因分类：
| 类别 | 说明 | 示例 |
|---|
| 变更引入 | 代码/配置/基础设施变更导致 | 部署了有 bug 的代码、配置项写错 |
| 容量不足 | 资源打满/扩容不及时 | 磁盘写满、连接池耗尽、流量超过预期 |
| 监控盲区 | 缺少告警或告警阈值不合理 | 没有监控该指标、告警阈值过高未触发 |
| 依赖故障 | 上下游服务/第三方故障 | CDN 故障、DNS 解析异常、云服务商故障 |
| 流程缺陷 | 发布/审批/应急流程缺失或未执行 | 没有灰度发布、缺少回滚方案、on-call 未响应 |
| 设计缺陷 | 架构/设计上的先天不足 | 单点故障、缺少降级方案、缓存击穿 |
第四步：改进措施制定（Action Items）
每条改进措施必须满足 SMART 原则：
| 要素 | 要求 | 反例 / 正例 |
|---|
| Specific | 具体明确 | "加强监控" -> "为 payment-service 添加连接池使用率监控" |
| Measurable | 可衡量 | "提高可用性" -> "支付成功率 SLO 从 99.5% 提升到 99.9%" |
| Assignable | 有明确负责人 | "大家注意一下" -> "张三负责，3/25 前完成" |
| Realistic | 可落地 | "重写整个支付系统" -> "为连接池添加泄漏检测中间件" |
| Time-bound | 有截止时间 | "尽快完成" -> "2024-03-25 前上线" |
改进措施分类：
| 类型 | 说明 | 优先级 |
|---|
| Mitigate | 防止同类问题再次发生 | 最高 - 下个迭代必须完成 |
| Detect | 更快发现同类问题 | 高 - 2 周内完成 |
| Prevent | 从根本上消除隐患 | 中 - 按优先级排入 backlog |
| Process | 改进流程/规范/文档 | 视情况 - 通常 1 周内完成 |
第五步：经验教训总结
从三个维度总结：
1. 做得好的地方（Keep Doing）
- 哪些响应环节做得好？为什么有效？
- 有什么值得沉淀为标准流程的？
2. 做得不好的地方（Stop Doing / Improve）
- 哪些环节拖慢了恢复速度？
- 有什么不必要的操作浪费了时间？
3. 运气因素（Lucky / Unlucky）
- 有什么是"碰巧"避免了更大影响的？
- 有什么是"碰巧"加剧了影响的？
- 这些运气因素揭示了什么潜在风险？
第六步：生成复盘文档
使用脚本生成格式化的 Markdown 文档：
python3 scripts/generate_postmortem.py --interactive
也可以将前几步收集的信息整理为 JSON 后直接生成：
python3 scripts/generate_postmortem.py --input incident.json --output postmortem.md
Blameless 无责文化原则
在整个复盘过程中，严格遵守以下原则：
- 关注系统，不追责个人 — "张三部署了有 bug 的代码"应改为"部署流程缺少自动化回归测试"
- 人犯错是正常的 — 如果一个人的失误就能导致重大故障，说明系统缺少防护机制
- 鼓励透明 — 越是坦诚地分享错误细节，越能找到真正的改进点
- 用数据说话 — 时间线和根因分析必须基于日志、监控数据、配置记录等客观证据
- 面向未来 — 复盘的目的是"下次怎么做更好"，而不是"这次谁做错了"
文档中的措辞检查清单：
| 避免 | 使用 |
|---|
| "张三的失误导致了..." | "变更流程缺少 X 环节，导致..." |
| "本应该检查的但没有检查" | "当前流程没有包含 X 检查步骤" |
| "粗心/疏忽导致了..." | "缺少自动化防护导致人工操作的 X 风险未被拦截" |
| "不负责任的操作" | "操作 SOP 未覆盖 X 场景" |
脚本参数说明
generate_postmortem.py
| 参数 | 说明 | 默认值 |
|---|
--interactive | 交互式模式，逐步引导输入事故信息 | - |
--input <file> | 从 JSON 文件读取事故信息 | - |
--output <file> | 输出文件路径 | stdout |
--format | 输出格式：markdown 或 json | markdown |
--template | 模板风格：standard（默认完整版）或 brief（精简版） | standard |
--lang | 文档语言：zh（中文）或 en（英文） | zh |
JSON 输入格式
{
"title": "支付服务 P99 延迟飙升至 30s",
"severity": "P1",
"start_time": "2024-03-15T14:32:00+08:00",
"end_time": "2024-03-15T16:45:00+08:00",
"impact": "华东区约 30% 用户支付失败，影响约 5000 笔交易",
"responders": ["张三 (SRE on-call)", "李四 (支付团队)"],
"timeline": [
{"time": "14:25", "type": "ACTION", "desc": "部署 payment-service v2.3.1"},
{"time": "14:32", "type": "TRIGGER", "desc": "支付成功率开始下降"
参考资料
- Google SRE Book - Postmortem Culture
- Etsy: Blameless PostMortems and a Just Culture
- PagerDuty Postmortem Guide
- The Infinite Hows (replacing 5 Whys)
