Systematic Debugging — 4-Phase Root Cause Protocol

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

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.