前置概念

systematic-debugging 是 Superpowers 纪律执行技能组的核心成员。297 行，是所有 skill 中最长的之一。它解决的问题是 agent 最危险的默认行为：在理解问题之前就提出修复方案。

它的威力不在于"教 agent 怎么 debug"——agent 本身就有 debug 能力。它的威力在于禁止 agent 在完成四阶段之前碰修复代码。它把 debug 从"直觉驱动的猜测"强制转变成"假设驱动的实验科学"。

逐层拆解

第 0 层：Description——阻断式触发

原文：

description: Use when encountering any bug, test failure, or unexpected behavior,before proposing fixes

agent 的默认行为：遇到 bug → 看错误信息 → 猜原因 → 提出修复。agent 不会主动"停下来做系统化调查"——它的第一反应是"我看到了问题，让我修它。"

这条指令把它扭成什么：

"before proposing fixes"——最关键的两个词。触发条件不是"when debugging"，是"在提出任何修复方案之前"。这意味着 agent 在看到错误信息的那一刻就应该加载这个 skill——不是在它想了一会觉得需要帮助的时候。

第 1 层：The Iron Law——全局第一优先级

原文：

## The Iron LawNO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRSTIf you haven't completed Phase 1, you cannot propose fixes.

agent 的默认行为：agent 的推理链是：错误信息 → 模式匹配 → "我知道这是什么问题" → 修复。Phase 1（系统化调查）在这条链中不存在。

这条指令把它扭成什么：

"NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST"——全大写的 Iron Law。不是"建议先调查"，是"禁止修复直到调查完成"。"If you haven't completed Phase 1, you cannot propose fixes"——把 Phase 1 变成了一个不可绕过的前置条件。这不是一个时间顺序的建议，是一个权限控制：没有 Phase 1 的完成状态，Phase 4 的修复是被锁定的。

第 2 层：四阶段不可跳过的门控

原文：

## The Four PhasesYou MUST complete each phase before proceeding to the next.### Phase 1: Root Cause Investigation**BEFORE attempting ANY fix:**1. Read Error Messages Carefully2. Reproduce Consistently3. Check Recent Changes4. Gather Evidence in Multi-Component Systems5. Trace Data Flow### Phase 2: Pattern Analysis1. Find Working Examples2. Compare Against References3. Identify Differences4. Understand Dependencies### Phase 3: Hypothesis and Testing1. Form Single Hypothesis2. Test Minimally3. Verify Before Continuing4. When You Don't Know### Phase 4: Implementation1. Create Failing Test Case2. Implement Single Fix3. Verify Fix4. If Fix Doesn't Work5. If 3+ Fixes Failed: Question Architecture

agent 的默认行为：agent 面对 bug 时，Phase 1-3 被压缩成一个跳跃："我看到了错误，这和上次见过的 X 问题很像，应该用 Y 方法修复。" 这不是实验科学——是直觉模式匹配。

这条指令把它扭成什么：

四个阶段各有具体的子步骤，每个子步骤有明确的成功标准：

Phase 1 的五步调查法：

1. 读错误信息："Don't skip past errors or warnings. Read stack traces completely." Agent 倾向于扫一眼错误类型就开始猜。这条指令要求读完整栈追踪。

2. 稳定复现："Can you trigger it reliably? If not reproducible → gather more data, don't guess." "不可复现 = 收集更多数据"是反直觉的——agent 会想要直接修"可能的原因"。但这条说：修一个不能复现的 bug = 无法验证修复。

3. 检查最近的改动：git diff, recent commits, new dependencies, config changes, environmental differences。五个具体维度确保 agent 不遗漏。

4. 跨组件证据收集：在多组件系统中，"before proposing fixes, add diagnostic instrumentation"——在每个组件边界记录输入输出。不是"我觉得问题在组件 X"，而是运行一次插桩确认到底是哪个组件。

5. 追踪数据流：引用 root-cause-tracing.md——"Where does bad value originate? Keep tracing up until you find the source. Fix at source, not at symptom."

Phase 2 的四步模式分析：

• 找工作中相似的代码（不是从记忆中找，是在这个 codebase 中找）
• 完整读参考实现，不要 skim
• 列出每一个差异，不管多小——"Don't assume 'that can't matter'"
• "What other components does this need? What settings, config, environment?"

Phase 3 的科学方法：

• "Form Single Hypothesis"——一次一个假设。不是"可能是 A、B 或 C"，是"我认为是 A，因为..."
• "Test Minimally"——最小的改动验证假设。"One variable at a time."
• "Verify Before Continuing"——验证了再往前走。没验证就走到 Phase 4 = 重来。

Phase 4 的核心规则【第 4 层会展开】。

第 3 层：3+ 失败 = 质疑架构——最激进的设计决策

原文：

4. **If Fix Doesn't Work** - STOP - Count: How many fixes have you tried? - If < 3: Return to Phase 1, re-analyze with new information - **If ≥ 3: STOP and question the architecture (step 5 below)** - DON'T attempt Fix #4 without architectural discussion5. **If 3+ Fixes Failed: Question Architecture** **Pattern indicating architectural problem:** - Each fix reveals new shared state/coupling/problem in different place - Fixes require "massive refactoring" to implement - Each fix creates new symptoms elsewhere **STOP and question fundamentals:** - Is this pattern fundamentally sound? - Are we "sticking with it through sheer inertia"? - Should we refactor architecture vs. continue fixing symptoms? **Discuss with your human partner before attempting more fixes** This is NOT a failed hypothesis - this is a wrong architecture.

agent 的默认行为：agent 的"修复失败"模式是：修 → 失败 → 再修 → 再失败 → 再修... 直到放弃或碰巧成功。它会尝试 5 次、10 次、15 次，每次调整策略但从不质疑"这个架构本身是不是对的"。

这条指令把它扭成什么：

"If ≥ 3: STOP and question the architecture"——这是整个 Superpowers 中最激进的设计决策。它把一个数字阈值（3）和一个架构级别的质疑（"这个模式从根本上是对的吗？"）绑在一起。

为什么要 3？因为：

• 第 1 次修复失败：可能是理解不够
• 第 2 次修复失败：可能是假设错误
• 第 3 次修复失败：大概率不是假设的问题——是架构的问题

三个具体的架构问题信号：

• "Each fix reveals new shared state/coupling/problem"——修复 A 暴露了 B，修复 B 暴露了 C
• "Fixes require 'massive refactoring'"——修一个小 bug 需要改 20 个文件
• "Each fix creates new symptoms elsewhere"——打地鼠

"DON'T attempt Fix #4 without architectural discussion"——第 4 次修复不是被禁止，是被锁在"和用户讨论架构"之后。这是技术层面 → 管理层面的升级。

第 4 层：Rationalization Table——16 条借口的预击杀

原文：

## Common Rationalizations| Excuse | Reality ||--------|---------|| "Issue is simple, don't need process" | Simple issues have root causes too. || "Emergency, no time for process" | Systematic debugging is FASTER than guess-and-check thrashing. || "Just try this first, then investigate" | First fix sets the pattern. Do it right from the start. || "I'll write test after confirming fix works" | Untested fixes don't stick. Test first proves it. || "Multiple fixes at once saves time" | Can't isolate what worked. Causes new bugs. || "Reference too long, I'll adapt the pattern" | Partial understanding guarantees bugs. Read it completely. || "I see the problem, let me fix it" | Seeing symptoms ≠ understanding root cause. || "One more fix attempt" (after 2+ failures) | 3+ failures = architectural problem. Question pattern, don't fix again. || ... | ... |

agent 的默认行为：这 16 条是从实际 debug 会话中采集的 agent 对自己说的原话。在压力下，agent 会逐条使用它们来让自己跳过流程。

这条指令把它扭成什么：

和 brainstorming 的 Anti-Pattern、using-superpowers 的 Red Flags 一样——合理化借口预击杀。但这里最特别的是第 8 条 "One more fix attempt" (after 2+ failures)——它直接对应第 3 层的"3+ 失败 = 质疑架构"规则。agent 在第 3 次失败后最自然的想法是"再试一次"，表格提前标记这是借口。

第 5 层：Red Flags——自我监控的触发器

原文：

## Red Flags - STOP and Follow ProcessIf you catch yourself thinking:- "Quick fix for now, investigate later"- "Just try changing X and see if it works"- "Add multiple changes, run tests"- "Skip the test, I'll manually verify"- "It's probably X, let me fix that"- "I don't fully understand but this might work"- "Pattern says X but I'll adapt it differently"- "Here are the main problems: [lists fixes without investigation]"- Proposing solutions before tracing data flow- **"One more fix attempt" (when already tried 2+)**- **Each fix reveals new problem in different place****ALL of these mean: STOP. Return to Phase 1.****If 3+ fixes failed:** Question the architecture (see Phase 4.5)

agent 的默认行为：agent 不会自发地元认知——它不会在做某件事的时候停下来问"我是不是在走捷径？"。

这条指令把它扭成什么：

11 个具体的思维触发器。每个都是 agent 在偏离流程时会对自己说的原话。Red Flags 起到了模式匹配的作用——agent 的思考中提到"Just try changing X and see"时，Red Flags 表触发 STOP。不需要自省——只需自匹配。

最后两行是双重约束：第一次出现在 Phase 4 规则中，第二次出现在 Red Flags 中，确保 agent 在流程的任何阶段遇到这个模式都能识别。

第 6 层：人类信号解读——外部校正的触发器

原文：

## your human partner's Signals You're Doing It Wrong**Watch for these redirections:**- "Is that not happening?" - You assumed without verifying- "Will it show us...?" - You should have added evidence gathering- "Stop guessing" - You're proposing fixes without understanding- "Ultra-think this" - Question fundamentals, not just symptoms- "We're stuck?" (frustrated) - Your approach isn't working**When you see these:** STOP. Return to Phase 1.

agent 的默认行为：当人说"Stop guessing"时，agent 可能理解为"我需要更好的猜测"而不是"我需要停下手头的工作回到调查阶段"。

这条指令把它扭成什么：

把用户的模糊不满映射到具体的流程状态。每句人类抱怨被翻译成一个明确的诊断：

• "Is that not happening?" → 你在假设而不是验证
• "Will it show us...?" → 你应该加诊断插桩
• "Stop guessing" → 你在 Phase 4 但你还没完成 Phase 1
• "Ultra-think this" → 回到架构层面，不是症状层面

这让 agent 在听到用户反馈时不是辩解或调整策略——是直接回到 Phase 1。

第 7 层：配套技术文件的引用网络

原文：

## Supporting TechniquesThese techniques are part of systematic debugging and available in this directory:- **root-cause-tracing.md** - Trace bugs backward through call stack- **defense-in-depth.md** - Add validation at multiple layers after finding root cause- **condition-based-waiting.md** - Replace arbitrary timeouts with condition polling**Related skills:**- **superpowers:test-driven-development** - For creating failing test case (Phase 4, Step 1)- **superpowers:verification-before-completion** - Verify fix worked before claiming success

agent 的默认行为：agent 在看 skill 时不会主动查找同一目录下的辅助文件——它只看 SKILL.md。

这条指令把它扭成什么：

引用网络——systematic-debugging 不是一个孤立的 skill，它是三个辅助技术文件 + 两个下游 skill 的中心节点。每份文件在什么时候使用被明确标注（root-cause-tracing 在 Phase 1.5 数据流追踪时，defense-in-depth 在 Phase 4 修复后，condition-based-waiting 在 flaky tests 时）。

总结：Systematic-Debugging 的 8 层约束

┌─────┬──────────────────────────┬──────────────────────────────┐│ 层│ 约束│ 对抗的 agent 默认行为 │├─────┼──────────────────────────┼──────────────────────────────┤│0│ description: "before proposing fixes" │ 看到 bug → 开始修││1│ Iron Law 全大写门控 │ 直觉 → 修复，跳过调查阶段 ││2│ 四阶段不可跳过，各有子步骤│ 压缩 Phase 1-3 成一个跳跃 ││3│ 3+ 失败 = 质疑架构 + 需要讨论 │ 无限循环修复，从不质疑架构 ││4│ 16 条合理化借口预击杀│ "这次是紧急情况"、"太简单了" ││5│ 11 条 Red Flags 模式匹配│ 不会自省"我是不是在走捷径" ││6│ 人类信号 → 流程状态映射 │ 把不满理解为"需要更好的猜测" ││7│ 引用网络（3 文件 + 2 skill）│ 只看 SKILL.md，忽略辅助文件 │└─────┴──────────────────────────┴──────────────────────────────┘

核心设计理念：Systematic-debugging 的约束层级体现了一个根本信念——调试是科学，不是艺术。科学方法的步骤是固定的（观察 → 假设 → 实验 → 验证 → 结论）。agent 的自然倾向是跳过假设和实验环节直接下结论——"这个 bug 的原因我一看就知道了"。

这个 skill 用 8 层约束把 agent 的认知路径从"模式匹配 → 修复"改写成"观察 → 稳定复现 → 检查改动 → 插桩收集证据 → 追踪数据流 → 对比工作代码 → 识别差异 → 形成单一假设 → 最小验证 → 如果验证通过 → 创建测试 → 单一修复 → 验证修复 → 如果修复失败 → 计数 → 如果 <3 → 回到观察 → 如果 ≥3 → 质疑架构。"

每一步都有一个 agent 如果不被约束就会跳过的理由，而每一步都有一个对应的预防机制。

附录：Systematic-Debugging SKILL.md 完整原文

---name: systematic-debuggingdescription: Use when encountering any bug, test failure, or unexpected behavior,before proposing fixes---# Systematic Debugging## OverviewRandom fixes waste time and create new bugs. Quick patches mask underlying issues.**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixesare failure.**Violating the letter of this process is violating the spirit of debugging.**## The Iron LawNO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRSTIf you haven't completed Phase 1, you cannot propose fixes.## When to UseUse for ANY technical issue: test failures, bugs, unexpected behavior, performanceproblems, build failures, integration issues.**Use this ESPECIALLY when:**- Under time pressure (emergencies make guessing tempting)- "Just one quick fix" seems obvious- You've already tried multiple fixes- Previous fix didn't work- You don't fully understand the issue**Don't skip when:**- Issue seems simple (simple bugs have root causes too)- You're in a hurry (rushing guarantees rework)- Manager wants it fixed NOW (systematic is faster than thrashing)## The Four PhasesYou MUST complete each phase before proceeding to the next.### Phase 1: Root Cause Investigation1. Read Error Messages Carefully - Don't skip past errors, read stack traces completely2. Reproduce Consistently - Can you trigger it reliably? If not → gather more data3. Check Recent Changes - git diff, recent commits, new dependencies, config changes4. Gather Evidence in Multi-Component Systems - Add diagnostic instrumentation at each component boundary5. Trace Data Flow - Where does bad value originate? Keep tracing up. Fix at source.### Phase 2: Pattern Analysis1. Find Working Examples - Locate similar working code in same codebase2. Compare Against References - Read reference implementation COMPLETELY3. Identify Differences - List every difference, however small4. Understand Dependencies - What other components, settings, config, environment?### Phase 3: Hypothesis and Testing1. Form Single Hypothesis - "I think X is the root cause because Y"2. Test Minimally - SMALLEST possible change, one variable at a time3. Verify Before Continuing - Did it work? Yes → Phase 4. No → New hypothesis4. When You Don't Know - Say "I don't understand X", don't pretend### Phase 4: Implementation1. Create Failing Test Case - MUST have before fixing2. Implement Single Fix - ONE change at a time, no "while I'm here"3. Verify Fix - Test passes? No other tests broken?4. If Fix Doesn't Work - STOP. Count fixes tried. <3 → Phase 1. ≥3 → step 55. If 3+ Fixes Failed: Question Architecture - STOP and question fundamentals Discuss with your human partner before attempting more fixes## Common Rationalizations| Excuse | Reality ||--------|---------|| "Issue is simple, don't need process" | Simple issues have root causes too || "Emergency, no time for process" | Systematic is FASTER than guess-and-check || "Just try this first, then investigate" | First fix sets the pattern || "I'll write test after confirming fix works" | Untested fixes don't stick || "Multiple fixes at once saves time" | Can't isolate what worked || "Reference too long, I'll adapt the pattern" | Partial understanding = bugs || "I see the problem, let me fix it" | Symptoms ≠ root cause || "One more fix attempt" (after 2+ failures) | 3+ = architectural problem |## Red Flags - STOP and Follow Process- "Quick fix for now, investigate later"- "Just try changing X and see if it works"- "Add multiple changes, run tests"- "Skip the test, I'll manually verify"- "It's probably X, let me fix that"- "I don't fully understand but this might work"- "Here are the main problems: [lists fixes without investigation]"- Proposing solutions before tracing data flow- "One more fix attempt" (when already tried 2+)- Each fix reveals new problem in different placeALL of these mean: STOP. Return to Phase 1.If 3+ fixes failed: Question the architecture.## your human partner's Signals You're Doing It Wrong- "Is that not happening?" - You assumed without verifying- "Will it show us...?" - You should have added evidence gathering- "Stop guessing" - You're proposing fixes without understanding- "Ultra-think this" - Question fundamentals, not just symptoms- "We're stuck?" (frustrated) - Your approach isn't workingWhen you see these: STOP. Return to Phase 1.## Supporting Techniques- root-cause-tracing.md - Trace bugs backward through call stack- defense-in-depth.md - Add validation at multiple layers- condition-based-waiting.md - Replace arbitrary timeouts with condition pollingRelated skills:- superpowers:test-driven-development - For creating failing test case- superpowers:verification-before-completion - Verify fix worked