bm-systematic-troubleshooting

name	bm.systematic-troubleshooting
description	系统化排查根因：4 阶段法（复现 → 缩小 → 假设 → 验证）。Use when something is broken, wrong, slow, weird, unexpected, intermittent, 出错, 报错, bug, 问题, 不对, 慢, 卡, 怪, 排查, 定位, debug, troubleshoot. 适用于代码 bug、产品异常、流程出错、数据不对——任何「事情没按预期发生」的场景。
source	opencrew
version	20260521.01

Skill: Systematic Troubleshooting（系统化排查）

先复现，再缩小，再假设，最后验证。绝不靠猜。 适用于所有「事情没按预期发生」的场景。

不只是代码 bug——产品流程异常、数据对不上、设备不工作、操作没反应、流程卡住，都适用。

---

核心原则

1. 先证据，后假设：没复现就别开始修
2. 缩小范围，不是放大：每一步都让问题边界更清晰
3. 假设要可证伪：能用一个动作验证 yes/no
4. 改最少的东西：一次只动一个变量
5. 修了之后必须验证：否则可能只是掩盖

---

4 阶段法

阶段 1：复现（Reproduce）

目标：让问题可控地、稳定地、最小步数地出现。

关键动作：

• 找最小复现步骤（删掉所有非必要步骤）
• 记录环境差异：什么时候出/什么时候不出
• 不能稳定复现的：记录频率和条件，不要跳过

问题分类（决定下一步策略）：

类型	特征	难度
必现	每次都出	低
条件触发	特定输入/状态/时间才出	中
偶发	时有时无，无规律	高（先想办法变成条件触发）
一次性	出过一次再没出	最高（先收集证据，等再次出现）

反模式：

• ❌ 没复现就开始改代码 → 改了不知道有没有用
• ❌ 复现一次就以为搞定了 → 偶发问题需要多次确认

阶段 2：缩小范围（Isolate）

目标：把"问题出在哪"的边界从大到小压缩。

方法：

方法	操作	适用
二分	砍一半看问题在不在	不知道在哪一段
切换	换数据/环境/设备/账号	怀疑环境
回退	退到一个已知好的版本	之前是好的
最小化	剥离到最小可复现	复杂系统
时间法	git bisect / 翻历史	回归问题

追问 5 次"为什么"：

• 表面：报错了
• 为什么报错？→ 函数返回 None
• 为什么是 None？→ 数据库查询没返回
• 为什么没返回？→ 字段名拼错了
• 为什么字段名拼错？→ 上周改了 schema 没同步
• 根因：变更管理流程缺失

修最深一层能修的，别修最表面那层。

阶段 3：假设（Hypothesize）

目标：基于证据列出 2-3 个最可能的根因，每个都能验证。

好假设的标准：

• ✅ 具体："config.json 里 port 字段是字符串 '8080' 而不是数字 8080"
• ✅ 可证伪：跑一个动作就知道对不对
• ❌ "可能是配置问题" — 太模糊
• ❌ "应该是缓存的问题" — 没证据

列假设按概率排序：

假设 1（最可能）：A 改坏了 B
  - 验证：跑 X 看 Y
  - 证据来源：错误信息提到 A

假设 2：环境差异
  - 验证：在 staging 复现
  - 证据来源：本地好用，线上不好用

假设 3（兜底）：第三方依赖
  - 验证：检查依赖版本
  - 证据来源：最近升级过

阶段 4：验证（Verify）

目标：确认假设对不对，然后再确认修复有效。

两步验证：

1. 验证根因：用阶段 3 的检验动作，确认假设成立

   • 假设错了 → 回阶段 3，换下一个假设
   • 假设对了 → 进入修复

2. 验证修复：

   • 改最少的代码 / 配置 / 步骤
   • 用阶段 1 的复现步骤再跑一次 — 必须不再触发问题
   • 跑相关测试 / 周边场景 — 没引入新问题
   • 用 bm.verification 给出完成报告

---

输出格式

排查过程要落档，方便用户跟进 / 后续复盘：

# 排查记录：{问题}

## 现象
- {一句话描述}
- 复现步骤：
  1. ...
  2. ...

## 环境
- {OS / 版本 / 配置}

## 排查时间线

### 阶段 1：复现 ✅
- 复现成功，必现
- 最小步骤：...

### 阶段 2：缩小
- 二分了 X，问题在 Y 模块
- 5why：... → 根因猜测：...

### 阶段 3：假设
1. ❌ A：验证后排除（证据：...）
2. ✅ B：成立（证据：...）

### 阶段 4：验证
- 修了 ...
- 复现步骤现在不再触发 ✅
- 周边测试通过 ✅

## 根因
{一句话}

## 修复
{改了什么，为什么这样改}

## 防再发
- {流程/检查项)

---

反模式

反模式	为什么错	正确做法
瞎改试运气	改对了不知道为啥，改错了浪费时间	先复现 + 假设
跳过复现直接猜	假设没证据，方向可能完全错	先稳定复现
一次改 5 个地方	不知道哪个起了作用	一次一个变量
改了能跑就不管	只是掩盖，可能再发	修根因，不修症状
看错误最外层	最外层是入口不是根因	stack trace 从内往外读
不看现有 issue	可能是已知问题	先搜 GitHub Issues / 历史排查记录
修完不验证	可能没修好或引入新问题	跑复现步骤 + 周边测试

---

非代码场景示例

场景：用户说"我的某个文件不见了"

1. 复现：让用户描述具体哪个文件、什么时候发现、上次见到是什么时候
2. 缩小：是真的删了还是搜不到？回收站/最近文件/git log？
3. 假设：误删 / 重命名 / 同步出问题 / 路径变了
4. 验证：每个假设对应一个查找动作

场景：会议没人来

1. 复现：之前几次会议谁来了？
2. 缩小：是这次特殊还是一直这样？同步发邀请的是谁？
3. 假设：邀请没发到 / 时间冲突 / 主题没吸引力 / 没人觉得自己该来
4. 验证：抽查几个人问情况

---

文件落点

• 排查记录 → ./working/troubleshoot-{topic}.md
• 重要问题的根因总结 → 归档到 ./postmortems/{date}-{topic}.md