systematic-debugging

Root-cause debugging skill for AI coding agents. Four phases: Reproduce, Analyze, Hypothesize, Implement.

Why

Most AI agents guess at fixes and retry until something sticks. This skill enforces the Iron Law: no fixes without understanding why the bug exists. Every fix requires confirmed evidence of the root cause.

Install

git clone https://github.com/d-wwei/systematic-debugging ~/.claude/skills/systematic-debugging

Or install automatically as part of Apex Forge:

bash apex-forge/skill/install.sh

Usage

/systematic-debugging

The skill activates a 4-phase investigation:

1. Reproduce — confirm the bug, classify it, capture evidence
2. Analyze — trace data flow, check recent changes, identify patterns
3. Hypothesize — generate 3+ testable hypotheses, test most likely first
4. Implement — write regression test first, then minimal fix, verify

Key Rules

• Iron Law: no fixes without root cause at direct evidence level or higher
• 3-Hypothesis Rule: minimum 3 distinct hypotheses before any fix
• 3-Strike Rule: after 3 failed hypotheses, your mental model is wrong. Start over from a different angle.

Output Contract

When used inside an orchestrator (e.g., Apex Forge):

output:
  status: enum [RESOLVED, UNRESOLVED, NEEDS_HELP]
  evidence_level: enum [guess, indirect, direct, confirmed, proven]
  root_cause: string
  fix_description: string

License

MIT

---

systematic-debugging

AI 编程 Agent 的根因调试 skill。四阶段：复现、分析、假设、实现。

为什么需要

多数 AI Agent 猜测修复、反复重试直到碰巧通过。这个 skill 强制执行 Iron Law：不理解 bug 成因就不许修复。每次修复都需要根因的确认级证据。

安装

git clone https://github.com/d-wwei/systematic-debugging ~/.claude/skills/systematic-debugging

或通过 Apex Forge 自动安装：

bash apex-forge/skill/install.sh

使用

/systematic-debugging

4 阶段调查流程：

1. 复现 — 确认 bug 存在，分类，采集证据
2. 分析 — 追踪数据流，检查近期变更，识别模式
3. 假设 — 生成 3+ 个可测试假设，从最可能的开始验证
4. 实现 — 先写回归测试，再最小修复，验证

核心规则

• Iron Law：根因未达到 direct 级证据前不修复
• 3 假设规则：修复前至少 3 个不同假设
• 3 失败规则：3 个假设都错，说明你的思维模型有问题，换角度重来

输出契约

output:
  status: enum [RESOLVED, UNRESOLVED, NEEDS_HELP]
  evidence_level: enum [guess, indirect, direct, confirmed, proven]
  root_cause: string
  fix_description: string

License

MIT