systematic-debugging

name	systematic-debugging
description	四阶段根因分析：调查、模式分析、假设测试、修复。铁律：没有根因就没有修复。禁止猜测性修复和症状压制。触发短语："调试"、"debug"、"排查"、"根因"。
allowed-tools	Read, Write, Edit, Glob, Grep, Bash

/systematic-debugging — 系统化调试

用结构化的四阶段流程定位和修复问题的根因。拒绝猜测性修复和症状压制。

铁律

没有根因就没有修复。

如果你无法清晰说出"问题的原因是 X，因为 Y"，就不要开始写修复代码。

四阶段流程

阶段 1：根因调查

目标：收集事实，理解问题的完整表现。

1. 复现问题，记录确切的错误信息和行为
2. 收集相关日志、堆栈跟踪、错误输出
3. 确定问题首次出现的时间点（git log、git bisect）
4. 圈定问题涉及的代码范围

# 有用的调查命令
git log --oneline -20                           # 最近提交
git log --all --oneline -- path/to/file         # 文件变更历史
git bisect start HEAD known-good-commit         # 二分定位

产出：一份事实清单，不含任何推测。

详细的根因追踪方法见 references/root-cause-tracing.md。

阶段 2：模式分析

目标：从事实中识别模式，缩小怀疑范围。

分析方向：

• 问题是否与特定输入相关
• 问题是否具有时间模式（总是发生 / 偶尔发生 / 特定条件下发生）
• 问题是否与特定代码路径相关
• 是否有类似的已知问题

产出：2 到 3 个可能的根因假设，按可能性排序。

阶段 3：假设测试

目标：通过实验验证或排除每个假设。

对每个假设：

1. 设计一个能证实或证伪它的实验
2. 执行实验
3. 记录结果
4. 根据结果更新假设排序

# 实验方法示例
# 添加诊断日志
# 修改输入数据
# 隔离组件运行
# 对比正常和异常环境的差异

如果 3 个以上的修复尝试失败，停下来质疑架构层面的假设。参考 references/defense-in-depth.md。

产出：确认的根因，附带实验证据。

阶段 4：修复实现

目标：修复根因，不是掩盖症状。

1. 编写测试复现问题（修复前测试应失败）
2. 修复根因
3. 确认测试通过
4. 检查是否有其他位置存在相同问题（全局搜索相同模式）
5. 运行完整测试套件确认无回归

修复守卫：

• 禁止通过降低日志级别来消除警告
• 禁止用 try/catch 吞掉异常
• 禁止用 @SuppressWarnings 忽略问题
• 禁止在不理解原因的情况下添加 sleep/retry

调试笔记

在调试过程中，维护一个调试笔记（可以在聊天中，不需要写入文件）：

问题：[一句话描述]
事实：
  - [事实 1]
  - [事实 2]
假设：
  1. [假设 1] — 状态：[待验证/已排除/已确认]
  2. [假设 2] — 状态：[待验证/已排除/已确认]
实验记录：
  - [实验 1]：[结果]
根因：[确认后填写]

参考资料

• references/root-cause-tracing.md：详细的根因追踪方法论
• references/defense-in-depth.md：多层防御思维
• references/condition-based-waiting.md：基于条件的等待替代 sleep