根因分析与故障复盘 · systematic-debugging

二次开发：本技能改编自 obra/superpowers 的 systematic-debugging（MIT © 2025 Jesse Vincent），在保留其核心方法论基础上，升级为「提示词 + 可执行 CLI」双形态，并做中文职场场景本地化。署名见本目录 NOTICE.md 与仓库 THIRD_PARTY_NOTICES.md。

这个技能做什么

把一个模糊的"出问题了"，通过四阶段强制串行的根因分析流程，收敛成一份结构化、可执行的复盘报告——不仅定位根因，还给出单点修复方案和流程改进建议。

核心原则一句话：未找到根因之前，绝不提修复方案。症状级修复等于失败。

四阶段（必须按顺序完成，前一阶段没做完不能跳到下一阶段）：

1. 根因调查：仔细读错误信息 → 稳定复现问题 → 检查最近变更 → 沿组件边界加观测，定位断点在哪一层 → 追溯数据流到源头。
2. 模式对比：找"正常工作"的对照案例 → 完整阅读参考实现 → 列出正常与异常之间的每一个差异（不管多小）→ 理解依赖与前提假设。
3. 单假设最小验证：一次只写一个假设（"我认为 X 是根因，因为 Y"）→ 做最小实验验证 → 验证失败就换假设，绝不在旧修复上叠加新修复。
4. 单点修复：先建一个能复现问题的失败用例 → 只改一处根因 → 验证修复有效且没引入新问题 → 如果已经试了 3 次修复都失败，立刻停下质疑架构和基本前提，而不是硬上第 4 次。

典型适用场景（中文职场高频）：

• 线上故障复盘：服务挂了、接口超时、数据错乱——先定位断点在哪一层，再修。
• 客诉根因分析：客户投诉某个功能不对——从复现开始，对比正常用户的差异，找到根因再回应。
• 质检异常：产品抽检不合格——沿生产流程加观测，找断点，而不是直接调参数碰运气。
• 流程事故复盘：审批卡住、报表对不上、跨部门协作出纰漏——追溯数据流，找信息在哪一层丢了。
• 业务指标异常排查：转化率掉了、留存降了——先找对照案例（什么时候是正常的），列差异，再提假设。

输入要求

• 必填（这也是 CLI 输入文件应包含的内容）：
  1. 问题现象：具体看到了什么异常？错误信息、报错截图文字、异常输出、数据偏差——越具体越好，不要只写"出问题了"。
  2. 环境信息：在什么系统/版本/配置/网络/场景下发生的？
  3. 已尝试的动作与结果：到目前为止试过哪些修复或排查？每一步的结果是什么？（这决定了是否触发"质疑基本假设"分支）
  4. 期望行为：正常情况下应该是什么样的？
• 可选但强烈建议： 5. 对照信息：有没有"正常工作"的案例（别的用户、别的环境、之前正常的时候）？
• 信息不足时：先向用户追问补全，不要凭空假设；实在补不上的地方标注"（待确认）"。

输出结构（模板见 scripts/templates/systematic-debugging.template.md）

一份完整的根因分析复盘报告，自上而下：

1. 问题现象与影响：一句话描述问题 + 影响范围（谁受影响、多少量、严重度分级）。
2. 复现步骤：可复现则给出精确步骤；不可复现则明确标注"暂不可稳定复现"，并说明已收集的证据。
3. 假设列表：3-5 个候选根因，每个假设配一个最小验证实验（怎么验证、预期看到什么结果、代价多大）。
4. 模式对比：与"正常情况"的差异清单——每一个差异列一行，标注"可能相关/无关/待验证"。
5. 最可能根因 + 修复方案：置信度（高/中/低）+ 判断依据；修复方案必须是单点（只改一处），附验证标准（怎么确认修好了、怎么确认没引入新问题）。
6. 复盘教训：流程改进建议——检查点加在哪一层、监控要补什么、以后怎么早发现。

工作流程

1. 根因调查（第一步）：先把现象、环境、已尝试动作全部理清；如果是多组件系统，必须沿组件边界逐层加观测（输入是什么、输出是什么、状态在哪层丢了），跑一次收集证据，定位断点在哪一层。停在：知道"坏值从哪一层开始出现"。
2. 模式对比（第二步）：找一个"正常工作"的对照案例，完整对比每一个细节差异，不要跳过任何看起来"不可能有关系"的点。停在：列完差异清单。
3. 单假设最小验证（第三步）：从差异清单里提假设，一次只验证一个；做最小实验，一次只改一个变量。验证成功 → 进入第四步；验证失败 → 换假设，不要在旧修复上叠加。停在：假设被证实或证伪。
4. 单点修复（第四步）：只修根因那一处，不做"顺手优化"；修复后按验证标准确认有效。如果用户已尝试 ≥3 次修复仍失败 → 触发"质疑基本假设"分支：停下来重新审视架构和前提，而不是硬上第 4 次。

质量规则（必须遵守）

• 未找到根因，不提修复方案：前一阶段没做完，绝不跳到下一阶段。
• 假设必须配验证方法：每个候选根因都要写清楚"怎么最小成本验证它"，不能只列假设不设实验。
• 一次只验证一个假设：禁止"同时改两个地方试试"，否则无法隔离哪个变量起了作用。
• 单点修复：修复方案只能改一处根因，禁止打包重构、顺手优化、捆绑改动。
• 3 次失败 = 质疑基本假设：如果用户已尝试 ≥3 次修复仍未解决，必须在报告里明确提示"基本假设可能有问题，建议重新审视架构/前提，而不是继续硬修"。
• 不编造环境信息：输入里没提供的环境细节，一律标注"（待确认）"，不要自己脑补。
• 症状级修复必须指出：如果用户的"修复"只是在掩盖症状而不是修根因，必须明确指出。
• 复现不了就标注：问题不可稳定复现时，不要硬编复现步骤，如实标注并说明已收集的证据。

边界与异常处理

• 用户跳过前几步直接要修复方案 → 拒绝，先回到根因调查阶段，说明"不定位根因就修，大概率是碰运气"。
• 用户已经试了 3 次以上修复 → 自动触发"质疑架构/前提"分支，报告里必须出现"基本假设可能有问题"的提示。
• 问题确实不可复现 / 环境相关 / 偶发 → 如实标注，报告里给出"已调查范围 + 建议加什么监控/日志以便下次定位"，不要硬编根因。
• 跨领域场景（客诉、质检、业务指标） → 方法论不变，只是把"组件"换成"流程环节"、"代码"换成"操作步骤/参数"。
• 信息严重不足（连现象都说不清） → 先追问：具体异常是什么？在哪发生的？期望是什么样？不要直接生成报告。

与脚本配合

• 批量 / 命令行场景：scripts/draft_systematic_debugging.py（纯标准库，一条命令跑通）；输入为问题描述文本（现象 / 环境 / 已尝试动作与结果 / 期望行为 / 可选对照信息），输出为根因分析复盘报告 Markdown。
• --attempts N：传入用户已尝试修复的次数；当 N ≥ 3 时，系统提示词自动加入"质疑基本假设"的强制提示。
• 自定义模板：复制 scripts/templates/systematic-debugging.template.md 修改后使用。