Systematic Debugging — 4-Phase Root Cause Protocol

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.