incident-retrospective

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 是一种通过反复追问"为什么"来穿透表面原因、找到根本原因的分析方法。

执行规则：

1. 从直接原因开始，每次追问"为什么会发生这个？"
2. 至少问 5 层，直到触及可改进的系统/流程层面
3. 每一层的回答必须基于事实和证据，不是猜测
4. 如果一个"为什么"有多个原因，分支展开分别分析
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 无责文化原则

在整个复盘过程中，严格遵守以下原则：

1. 关注系统，不追责个人 — "张三部署了有 bug 的代码"应改为"部署流程缺少自动化回归测试"
2. 人犯错是正常的 — 如果一个人的失误就能导致重大故障，说明系统缺少防护机制
3. 鼓励透明 — 越是坦诚地分享错误细节，越能找到真正的改进点
4. 用数据说话 — 时间线和根因分析必须基于日志、监控数据、配置记录等客观证据
5. 面向未来 — 复盘的目的是"下次怎么做更好"，而不是"这次谁做错了"

文档中的措辞检查清单：

避免	使用
"张三的失误导致了..."	"变更流程缺少 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)