---
name: systematic-debugging
description: >
  提供系统化根因定位流程，避免在复杂缺陷里靠猜测叠加修补。
  当问题难复现、跨模块、连续修错或需要先证明根因再改代码时使用。
---

# Systematic Debugging

## 用途

- 把“先猜一个修法试试”改成“先收敛证据、再验证假设”。
- 适合复杂仓库、跨边界链路、间歇性问题和连续修错的场景。

## 默认做法

1. 先冻结“继续乱改代码”的冲动，收敛最小复现、错误现象、最近变更和影响边界。
2. 从症状沿数据流、调用链或状态变化往回追，找出第一个与预期不一致的点，而不是只盯最终报错位置。
3. 每轮只保留一个最强根因假设；用额外日志、断言、最小实验或对照路径去证伪它。
4. 只有在根因被证实时才落修复；修复优先配套失败用例、稳定复现脚本或明确回归检查。
5. 修复完成后，把验证结果回交实现角色、QA 或 `/verify`，不要让调试结论停留在个人上下文里。

## 触发信号

- 已经尝试 2 次以上修改，但问题仍未消失或出现新副作用。
- 报错位置明显只是表象，真实原因可能在上游输入、配置、状态同步或依赖边界。
- 问题涉及多个模块、线程、服务、浏览器状态或异步链路。
- 需要先证明根因，才能决定是改代码、补测试、修配置还是升级处理。

## 配套约束

1. 先收敛入口、边界、相关规则和已有实现，再开始下判断。
2. 需要把修复闭环跑完时，接 `/verify` 或相应测试流程。
3. 涉及线上故障、止血或跨团队协调时，并行遵循事故分级、升级与同步 runbook。
4. 若连续 3 轮假设都被证伪，或怀疑涉及架构/需求层错误，升级给 `tech-lead` 或 `architect`，不要继续叠加试错。