# Incident Retrospective

> 线上事故复盘与结构化 Blameless Postmortem 撰写工具，遵循 SRE 最佳实践。帮助用户撰写专业的事故复盘报告，通过六步 SOP 引导完成从时间线梳理、5 Whys 根因分析到制定 SMART 改进措施的全过程，输出格式化的复盘文档。当用户需要撰写事故复盘、进行根因分析（RCA）、创建 blameless postmortem、分析线上故障、制定改进措施（action items）或总结事故教训时触发，常见于提到 postmortem、事故复盘、故障分析、RCA、5 Whys、incident review、故障报告等关键词的场景。

- Skill: `serejaris/incident-retrospective` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add serejaris/incident-retrospective`
- Raw SKILL.md: https://api.skillmd.com/api/skills/serejaris/incident-retrospective/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: serejaris (https://skillmd.com/u/serejaris)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/serejaris/incident-retrospective

---


# postmortem-writer

基于 Google SRE 和行业最佳实践的 **Blameless Postmortem** 撰写流程。通过结构化的 SOP 引导你完成从事故信息收集、时间线梳理、5 Whys 根因分析到改进措施制定的完整复盘过程，输出专业的事故复盘文档。

核心理念：**Blameless（无责文化）** — 关注系统和流程的改进，而不是追责个人。

## Quick Start

**交互式复盘**（推荐）：直接描述你的事故情况，Agent 将按照 SOP 流程引导你逐步完成复盘。

**一键生成文档**：如果你已经有完整的事故信息，可以用脚本快速生成格式化的复盘文档：

```bash
python3 scripts/generate_postmortem.py --interactive
```

或提供 JSON 输入直接生成：

```bash
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 文档：

```bash
python3 scripts/generate_postmortem.py --interactive
```

也可以将前几步收集的信息整理为 JSON 后直接生成：

```bash
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 输入格式

```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": "支付成功率开始下降"},
    {"time": "14:35", "type": "DETECT", "desc": "监控告警触发"},
    {"time": "15:25", "type": "ACTION", "desc": "回滚到 v2.3.0"},
    {"time": "15:30", "type": "RESOLVE", "desc": "服务恢复"}
  ],
  "five_whys": [
    {"level": 1, "question": "为什么延迟飙升？", "answer": "数据库连接池耗尽"},
    {"level": 2, "question": "为什么连接池耗尽？", "answer": "新版本未正确释放连接"},
    {"level": 3, "question": "为什么没在上线前发现？", "answer": "测试未覆盖连接释放"},
    {"level": 4, "question": "为什么没有这类测试？", "answer": "无资源泄漏测试规范"},
    {"level": 5, "question": "为什么没有规范？", "answer": "缺少资源管理 checklist"}
  ],
  "root_cause": "缺少资源泄漏自动化检测机制和 code review 规范",
  "root_cause_category": "流程缺陷",
  "action_items": [
    {
      "type": "mitigate",
      "desc": "为连接池添加泄漏检测和自动回收机制",
      "owner": "李四",
      "due": "2024-03-25",
      "priority": "P0"
    },
    {
      "type": "detect",
      "desc": "添加连接池使用率监控和告警",
      "owner": "张三",
      "due": "2024-03-22",
      "priority": "P0"
    }
  ],
  "lessons": {
    "keep_doing": ["告警后 3 分钟内 SRE 响应", "回滚决策果断"],
    "improve": ["部署后需要自动化的 smoke test", "告警升级机制需优化"],
    "lucky": ["故障发生在下午非高峰时段，否则影响更大"]
  }
}
```

---

## 参考资料

- Google SRE Book - Postmortem Culture
- Etsy: Blameless PostMortems and a Just Culture
- PagerDuty Postmortem Guide
- The Infinite Hows (replacing 5 Whys)