# 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 -->


## Quick Use

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

---

## Intro

Systematic Debugging is a Claude Code skill that enforces a strict 4-phase root-cause investigation protocol. Widely shared on Reddit r/ClaudeAI and Hacker News, the methodology achieves roughly 95% first-try fix success vs. ~40% for ad-hoc approaches. Core principle: never touch code before investigating the root cause.

Best for developers who want Claude Code to debug systematically instead of guessing fixes.
Compatible tools: Claude Code (any project, any language).

---

## The 4-Phase Protocol

### Phase 1: Root-Cause Investigation
Before editing code: read the error → reproduce it reliably → inspect recent changes → gather diagnostic evidence → trace the data flow

### Phase 2: Pattern Analysis
Find functionally similar working code → compare differences one by one → map dependencies

### Phase 3: Hypothesis & Test
Propose a single hypothesis → design the smallest test → predict the outcome → execute and observe → confirm or refute

### Phase 4: Implementation
Write a failing test → implement a focused fix → verify the test passes → run the full suite

### Key Rule
**3-strike rule**: after 3 consecutive failed fixes → stop, this is an architecture problem, not a simple bug.

### FAQ

**Q: What is this?**
A: A 4-phase root-cause investigation debugging skill that forces investigation before fixing, with ~95% first-try fix rate.

**Q: Is it free?**
A: Fully free — just copy the skill file into your project.

---

## 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)


---
Source: https://tokrepo.com/en/workflows/systematic-debugging-4-phase-root-cause-protocol-78ed006e
Author: Skill Factory