Debug Code Using Four-Phase Root Cause Analysis

This skill applies a four-phase root-cause-first debugging methodology, built on the core principle that no fix should be applied without root-cause investigation first - never patch symptoms that mask the underlying problem. Phase 1, root cause investigation, reads error messages thoroughly, reproduces the issue consistently since an unverifiable fix isn't a real fix, examines recent changes, gathers diagnostic evidence like logs and stack traces, and traces data flow through a specific technique: observe the symptom, find the immediate cause, ask what called this to map the call chain upward, and keep tracing until the original trigger is found, never fixing solely where the error appears. Phase 2, pattern analysis, locates similar working code, compares implementations completely rather than skimming, and identifies what differs and what the broken code depends on. Phase 3, hypothesis and testing, applies the scientific method: form one clear hypothesis, design a minimal single-variable test, predict the outcome, run it, verify against the prediction, then iterate or proceed. Phase 4, implementation, creates a failing test case that captures the bug, implements a single fix addressing the root cause rather than symptoms, verifies the test passes, runs the full suite for regressions, and stops to re-evaluate if the fix fails - with a hard rule that three or more consecutive failed fixes signal an architectural problem requiring team discussion, not more patches.

It lists red-flag thoughts that signal a process violation, such as reaching for a quick fix to investigate later, trying one more fix after multiple failures, assuming something should work without understanding why, or dismissing a difference as it works on my machine without investigating it, plus warning signs of deeper architectural problems where consecutive fixes reveal new problems elsewhere, calling for stopping and discussing rather than continuing to patch. It provides specific playbooks for common scenarios: test failures, by reading the full trace, checking the assertion, test setup, and test data, then tracing to the value's source; runtime errors, by capturing the trace, finding the throwing line, checking for undefined or null values, tracing backward, and adding validation at the source; "it worked before" regressions, by using git bisect to find the breaking commit, comparing against the prior working version, and fixing at the assumption that changed; and intermittent failures, by checking for race conditions, shared mutable state, async operation ordering, and timing dependencies, then adding deterministic synchronization. A pre-completion checklist and stated success metrics - roughly a 95 percent first-time fix rate for systematic debugging versus roughly 40 percent for ad-hoc approaches - reinforce the discipline.

Use it when investigating bugs, fixing test failures, or troubleshooting unexpected behavior - not for applying a quick symptom patch without understanding why something is failing.

Given a bug report, error, or failing test, it produces a documented root cause, a tested hypothesis, a minimal fix addressing that root cause, and a new regression test proving the fix.

Works alongside a testing-patterns skill to create the reproducing test before implementing any fix, and uses git bisect for regression hunting.

Developers debugging non-obvious failures who want a disciplined, evidence-based process instead of trial-and-error patching - especially useful for catching when repeated failed fix attempts signal a deeper architectural problem rather than a code-level bug.