"随机修 bug 浪费时间和创造新 bug。快速补丁掩盖底层问题。修症状 = 失败。"
前置概念
systematic-debugging 是 Superpowers 纪律执行技能组的核心成员。297 行，是所有 skill 中最长的之一。它解决的问题是 agent 最危险的默认行为：在理解问题之前就提出修复方案。
它的威力不在于"教 agent 怎么 debug"------agent 本身就有 debug 能力。它的威力在于禁止 agent 在完成四阶段之前碰修复代码。它把 debug 从"直觉驱动的猜测"强制转变成"假设驱动的实验科学"。
逐层拆解
第 0 层：Description------阻断式触发
原文：
yaml
description: Use when encountering any bug, test failure, or unexpected behavior,
before proposing fixesagent 的默认行为：遇到 bug → 看错误信息 → 猜原因 → 提出修复。agent 不会主动"停下来做系统化调查"------它的第一反应是"我看到了问题，让我修它。"
这条指令把它扭成什么：
"before proposing fixes"------最关键的两个词。触发条件不是"when debugging"，是"在提出任何修复方案之前"。这意味着 agent 在看到错误信息的那一刻就应该加载这个 skill------不是在它想了一会觉得需要帮助的时候。
第 1 层：The Iron Law------全局第一优先级
原文：
objectivec
## The Iron Law
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
If 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 层：四阶段不可跳过的门控
原文：
markdown
## The Four Phases
You MUST complete each phase before proceeding to the next.
### Phase 1: Root Cause Investigation
**BEFORE attempting ANY fix:**
1. Read Error Messages Carefully
2. Reproduce Consistently
3. Check Recent Changes
4. Gather Evidence in Multi-Component Systems
5. Trace Data Flow
### Phase 2: Pattern Analysis
1. Find Working Examples
2. Compare Against References
3. Identify Differences
4. Understand Dependencies
### Phase 3: Hypothesis and Testing
1. Form Single Hypothesis
2. Test Minimally
3. Verify Before Continuing
4. When You Don't Know
### Phase 4: Implementation
1. Create Failing Test Case
2. Implement Single Fix
3. Verify Fix
4. If Fix Doesn't Work
5. If 3+ Fixes Failed: Question Architectureagent 的默认行为：agent 面对 bug 时，Phase 1-3 被压缩成一个跳跃："我看到了错误，这和上次见过的 X 问题很像，应该用 Y 方法修复。" 这不是实验科学------是直觉模式匹配。
这条指令把它扭成什么：
四个阶段各有具体的子步骤，每个子步骤有明确的成功标准：
Phase 1 的五步调查法：
-
读错误信息："Don't skip past errors or warnings. Read stack traces completely." Agent 倾向于扫一眼错误类型就开始猜。这条指令要求读完整栈追踪。
-
稳定复现："Can you trigger it reliably? If not reproducible → gather more data, don't guess." "不可复现 = 收集更多数据"是反直觉的------agent 会想要直接修"可能的原因"。但这条说：修一个不能复现的 bug = 无法验证修复。
-
检查最近的改动 ：
git diff, recent commits, new dependencies, config changes, environmental differences。五个具体维度确保 agent 不遗漏。 -
跨组件证据收集：在多组件系统中，"before proposing fixes, add diagnostic instrumentation"------在每个组件边界记录输入输出。不是"我觉得问题在组件 X"，而是运行一次插桩确认到底是哪个组件。
-
追踪数据流 ：引用
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+ 失败 = 质疑架构------最激进的设计决策
原文：
vbnet
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 discussion
5. **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 条借口的预击杀
原文：
vbnet
## 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------自我监控的触发器
原文：
vbnet
## Red Flags - STOP and Follow Process
If 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 层：人类信号解读------外部校正的触发器
原文：
python
## 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 层：配套技术文件的引用网络
原文：
markdown
## Supporting Techniques
These 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 successagent 的默认行为 ：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 层约束
objectivec
┌─────┬──────────────────────────┬──────────────────────────────┐
│ 层 │ 约束 │ 对抗的 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 完整原文
markdown
---
name: systematic-debugging
description: Use when encountering any bug, test failure, or unexpected behavior,
before proposing fixes
---
# Systematic Debugging
## Overview
Random fixes waste time and create new bugs. Quick patches mask underlying issues.
**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.
## When to Use
Use for ANY technical issue: test failures, bugs, unexpected behavior, performance
problems, 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 Phases
You MUST complete each phase before proceeding to the next.
### Phase 1: Root Cause Investigation
1. Read Error Messages Carefully - Don't skip past errors, read stack traces completely
2. Reproduce Consistently - Can you trigger it reliably? If not → gather more data
3. Check Recent Changes - git diff, recent commits, new dependencies, config changes
4. Gather Evidence in Multi-Component Systems - Add diagnostic instrumentation at
each component boundary
5. Trace Data Flow - Where does bad value originate? Keep tracing up. Fix at source.
### Phase 2: Pattern Analysis
1. Find Working Examples - Locate similar working code in same codebase
2. Compare Against References - Read reference implementation COMPLETELY
3. Identify Differences - List every difference, however small
4. Understand Dependencies - What other components, settings, config, environment?
### Phase 3: Hypothesis and Testing
1. Form Single Hypothesis - "I think X is the root cause because Y"
2. Test Minimally - SMALLEST possible change, one variable at a time
3. Verify Before Continuing - Did it work? Yes → Phase 4. No → New hypothesis
4. When You Don't Know - Say "I don't understand X", don't pretend
### Phase 4: Implementation
1. Create Failing Test Case - MUST have before fixing
2. 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 5
5. 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 place
ALL 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 working
When 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 polling
Related skills:
- superpowers:test-driven-development - For creating failing test case
- superpowers:verification-before-completion - Verify fix worked