Azzygoatcoder Systematic Debugging
Overview
Core principle: ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
Violating the letter of this process is violating the spirit of debugging.
The Iron Law
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
If you haven't completed Phase 1, you cannot propose fixes.
场景判定（先定轻重，再定流程）
| 场景 | 力度 |
|---|---|
| 生产环境、正式项目、共享代码、反复出现的 bug | 完整四阶段：根因 → 模式 → 假设验证 → 实施 |
| 个人业余项目、低风险探索、一次性脚本 | 轻量调试：至少做到「稳定复现 → 定位根因 → 验证修复」；不需要形式上把四阶段全走一遍 |
| 纯 throwaway / 临时现象 | 可不深挖，但不要把这个修复当作"已验证"提交 |
判断标准：这个 bug 会浪费别人/后续/生产多少时间？ 低风险就快走，高成本就按完整流程。完整流程不是仪式，是"这个错误值得花时间"时的护城河。
⚠️ 与 references/debugging-guide.md 的优先级：该文件是上游原文，里面写着 "You MUST complete each phase" 并把"问题很简单不需要流程"列为 Common Rationalization。上面这张场景判定表是本地新增的、优先于它的—— 但那句 rationalization 警告的失效模式仍然成立：判定为「轻量」不代表可以跳过根因定位（轻量路径第 2 步 就是定位根因）。换句话说：可以少走阶段，不可以不做根因。 拿不准按「完整四阶段」走。
Quick Reference
| Phase | Key Activities | Success Criteria |
|---|---|---|
| 1. Root Cause | Read errors, reproduce, check changes, gather evidence | Understand WHAT and WHY |
| 2. Pattern | Find working examples, compare | Identify differences |
| 3. Hypothesis | Form theory, test minimally | Confirmed or new hypothesis |
| 4. Implementation | Create test, fix, verify | Bug resolved, tests pass |
完整四阶段、Red Flags、Common Rationalizations 和 Supporting Techniques 见 references/debugging-guide.md。
轻量路径（个人/低风险项目）
- 先复现：能不能稳定触发？不能，先补数据/日志，别猜。
- 定位根因：读错误信息、看最近改动、追到数据源头。至少确定“是哪里错了”，而不是“哪里看起来像错”。
- 最小修复：一次只改一个变量，验证修复是否生效。
- 验收：确认问题消失；如果影响真实使用，补一个最小回归测试。
Red Flags（速记）
- 还没定位根因就开始改
- “先快速修一下，之后再查”
- 一次改多个地方
- 3 次以上修复失败还在继续
遇到这些，STOP 回到根因调查。
Supporting Techniques
root-cause-tracing.md— Trace bugs backward through call stack to find original triggerdefense-in-depth.md— Add validation at multiple layers after finding root causecondition-based-waiting.md— Replace arbitrary timeouts with condition polling
完整展开见 references/debugging-guide.md。