前置概念
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 Law
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
If you haven't completed Phase 1, you cannot propose fixes.
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 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 Architecture
agent 的默认行为：面对 bug 时，Phase 1 到 Phase 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 的核心规则，将在下一层展开。
第 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 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 的“修复失败”模式是什么？修 → 失败 → 再修 → 再失败 → 再修...直到放弃，或者碰巧成功。它会尝试 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. |
| ... | ... |
这 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 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 不会自发地进行元认知，它不会在做某件事的时候停下来问“我是不是在走捷径？”
这里提供了 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.
当人说“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 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 success
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 │ 看到 bug → 开始修 │
│ │ proposing fixes" │ │
│ 1 │ Iron Law 全大写门控 │ 直觉 → 修复，跳过调查阶段 │
│ 2 │ 四阶段不可跳过，各有子步骤│ 压缩 Phase 1-3 成一个跳跃 │
│ 3 │ 3+ 失败 = 质疑架构 + │ 无限循环修复，从不质疑架构 │
│ │ 需要讨论 │ │
│ 4 │ 16 条合理化借口预击杀 │ "这次是紧急情况"、"太简单了" │
│ 5 │ 11 条 Red Flags 模式匹配 │ 不会自省"我是不是在走捷径" │
│ 6 │ 人类信号 → 流程状态映射 │ 把不满理解为"需要更好的猜测" │
│ 7 │ 引用网络（3 文件 + 2 │ 只看 SKILL.md，忽略辅助文件 │
│ │ skill） │ │
└─────┴──────────────────────────┴──────────────────────────────┘
核心设计理念：Systematic-debugging 的约束层级，体现了一个根本信念——调试是科学，不是艺术。科学方法的步骤是固定的（观察 → 假设 → 实验 → 验证 → 结论）。agent 的自然倾向是跳过假设和实验环节，直接下结论——“这个 bug 的原因我一看就知道了。”
这个 skill 用 8 层约束，把 agent 的认知路径从“模式匹配 → 修复”，改写成了一整套完整流程：观察 → 稳定复现 → 检查改动 → 插桩收集证据 → 追踪数据流 → 对比工作代码 → 识别差异 → 形成单一假设 → 最小验证 → 如果验证通过 → 创建测试 → 单一修复 → 验证修复 → 如果修复失败 → 计数 → 如果 <3 → 回到观察 → 如果 ≥3 → 质疑架构。每一步都有一个 agent 如果不被约束就会跳过的理由，而每一步都有一个对应的预防机制。
附录：Systematic-Debugging SKILL.md 完整原文
---
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
