# Systematic Debugging — 4-Phase Root Cause Protocol

> Claude Code skill that enforces a scientific 4-phase debugging methodology: investigate, analyze patterns, test hypotheses, then fix. Achieves 95% first-time fix rate vs 40% with ad-hoc approaches.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

## Quick Use

1. Copy the skill content below
2. Save to `.claude/skills/systematic-debugging.md` in your project
3. Claude Code auto-loads it on next conversation

Or install from the showcase:
```bash
git clone https://github.com/ChrisWiles/claude-code-showcase.git
cp -r claude-code-showcase/.claude/skills/systematic-debugging .claude/skills/
```

---

## Intro

Systematic Debugging is a Claude Code skill that enforces a rigorous 4-phase root cause investigation protocol before any code fix is attempted. Shared widely across Reddit r/ClaudeAI and Hacker News, this methodology achieves approximately 95% first-time fix rate compared to 40% with ad-hoc "whack-a-mole" approaches. The core principle is simple but powerful: NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST. It prevents the common anti-pattern of symptom-chasing that creates cascading bugs.

Best for: developers who want Claude Code to debug systematically instead of guessing at fixes.
Works with: Claude Code (any project, any language).
Setup time: under 1 minute.

---

## Systematic Debugging — The 4-Phase Protocol

### Phase 1: Root Cause Investigation

**Goal:** Understand what's happening before attempting to fix.

Before modifying ANY code:
- Read error messages thoroughly — every word matters
- Reproduce the issue consistently with minimal steps
- Examine recent changes that could have introduced the bug
- Gather diagnostic evidence: logs, stack traces, network requests
- Trace data flow through the complete call chain

**Tracing Technique:**
```
Symptom → Immediate Cause → Call Chain → Invalid Data Origin → Original Trigger
```

Never fix problems where errors appear — always trace to the original trigger point.

### Phase 2: Pattern Analysis

**Goal:** Find comparable working code to identify differences.

- Locate functionally similar code that WORKS correctly
- Perform complete side-by-side implementation comparison
- Identify specific differences between working and broken versions
- Map code dependencies to understand the full impact chain

### Phase 3: Hypothesis & Testing

**Goal:** Apply scientific methodology to validate the cause.

1. Formulate a **single clear hypothesis** about the root cause
2. Design a **minimal test** that changes only one variable
3. **Predict** the expected outcome before running the test
4. Execute and **observe** — does reality match prediction?
5. **Refine** hypothesis or proceed based on results

If the test disproves your hypothesis, go back to Phase 1. Do NOT guess a new fix.

### Phase 4: Implementation

**Goal:** Fix properly with verification.

1. **Create a failing test** that captures the exact bug behavior
2. Implement a **focused fix** addressing only the root cause
3. Verify the **failing test now passes**
4. Run the **full test suite** to check for regressions
5. If the fix fails on first attempt → **STOP** and reassess

### Critical Rules

#### The "3-Fails Rule"
> If three consecutive fix attempts fail, **HALT**. This signals an architectural problem, not a simple bug. Step back and re-examine assumptions.

#### Red Flags (Process Violations)
- "Quick fix for now, investigate later" ← NO
- Multiple consecutive fix attempts ← STOP
- Fixing without understanding the cause ← FORBIDDEN
- "It works on my machine" without investigation ← INADEQUATE

### Debugging Checklist

Before marking any bug resolved:
- [ ] Root cause identified and documented
- [ ] Hypothesis formed and tested scientifically
- [ ] Fix addresses root cause, not symptoms
- [ ] Failing test created before fix
- [ ] Test passes with fix applied
- [ ] Full test suite passes (no regressions)
- [ ] No "quick fix" rationalizations
- [ ] Fix is minimal and focused

### Success Metrics

| Approach | First-Time Fix Rate | Regression Rate |
|----------|-------------------|-----------------|
| **Systematic** | ~95% | Low |
| **Ad-hoc** | ~40% | High |

### FAQ

**Q: What is the Systematic Debugging skill?**
A: A Claude Code skill that enforces a 4-phase root cause investigation protocol — investigate, analyze patterns, test hypotheses, then fix. It prevents "whack-a-mole" debugging and achieves ~95% first-time fix rate.

**Q: Is it free?**
A: Yes, fully open-source. Copy the skill file to your project.

**Q: Does it work with any programming language?**
A: Yes. The methodology is language-agnostic — it works for Python, TypeScript, Rust, Go, or any other language.

---

## Source & Thanks

> From [ChrisWiles/claude-code-showcase](https://github.com/ChrisWiles/claude-code-showcase). Community-shared skill.
>
> [systematic-debugging](https://github.com/ChrisWiles/claude-code-showcase/tree/main/.claude/skills/systematic-debugging) — Community verified

Thank you to ChrisWiles for codifying this debugging methodology into a reusable Claude Code skill.

---

<!-- ZH -->

## 快速使用

1. 复制下方技能内容
2. 保存到项目的 `.claude/skills/systematic-debugging.md`
3. Claude Code 下次对话自动加载

---

## 简介

Systematic Debugging 是一个 Claude Code 技能，强制执行严格的 4 阶段根因调查协议。在 Reddit r/ClaudeAI 和 Hacker News 上广泛分享，该方法论的首次修复成功率约 95%，而随意修复方法仅约 40%。核心原则：在调查根因之前，绝不进行任何代码修改。

适合人群：希望 Claude Code 系统化调试而非猜测修复的开发者。
兼容工具：Claude Code（任何项目、任何语言）。

---

## 4 阶段协议

### 阶段 1：根因调查
修改代码之前：读错误信息 → 稳定复现 → 检查近期变更 → 收集诊断证据 → 追踪数据流

### 阶段 2：模式分析
找到功能类似的正常代码 → 逐一比较差异 → 映射依赖关系

### 阶段 3：假设与测试
提出单一假设 → 设计最小测试 → 预测结果 → 执行观察 → 确认或推翻

### 阶段 4：实施
创建失败测试 → 实施聚焦修复 → 验证测试通过 → 运行完整测试套件

### 关键规则
**3 次失败规则**：连续 3 次修复失败 → 停下，这是架构问题，不是简单 bug。

### FAQ

**Q: 这是什么？**
A: 4 阶段根因调查调试技能，强制先调查后修复，首次修复率 ~95%。

**Q: 免费吗？**
A: 完全免费，复制技能文件到项目即可。

---

## 来源与感谢

> From [ChrisWiles/claude-code-showcase](https://github.com/ChrisWiles/claude-code-showcase). Community-shared skill.
>
> [systematic-debugging](https://github.com/ChrisWiles/claude-code-showcase/tree/main/.claude/skills/systematic-debugging)

---
Source: https://tokrepo.com/en/workflows/78ed006e-b022-4e92-bf65-df8b53afd2f4
Author: Skill Factory