Debug Code Using Four-Phase Root Cause Analysis
A four-phase root-cause-first debugging skill - no fixes without investigation, hypothesis testing, and a regression test.
Why it matters
Systematically investigate and fix bugs by tracing root causes through a four-phase methodology that prevents symptom-focused patches and ensures fixes address underlying problems rather than masking them.
Outcomes
What it gets done
Trace errors backward through call chains to find original triggers instead of fixing where symptoms appear
Compare broken code with working examples to identify critical differences and dependencies
Formulate and test single-variable hypotheses using the scientific method before implementing fixes
Create failing test cases that reproduce bugs and verify fixes don't introduce regressions
Install
Add it to your toolbox
Run in your project directory:
curl -fsSL https://spark.entire.vc/get/ag-code-showcase-systematic-debugging | bash Overview
Systematic Debugging
This skill runs a four-phase debugging process - root cause investigation, pattern analysis, hypothesis testing, and implementation - requiring a documented root cause and a regression test before any fix is considered done. Use it when investigating bugs, fixing test failures, or troubleshooting unexpected behavior. Not for quick symptom patches without root-cause understanding.
What it does
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.
When to use - and when NOT to
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.
Inputs and outputs
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.
Integrations
Works alongside a testing-patterns skill to create the reproducing test before implementing any fix, and uses git bisect for regression hunting.
Who it's for
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.
Source README
Systematic Debugging
When to Use
Use this skill when you need four-phase debugging methodology with root cause analysis. Use when investigating bugs, fixing test failures, or troubleshooting unexpected behavior. Emphasizes NO FIXES WITHOUT ROOT CAUSE FIRST.
Core Principle
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.
Never apply symptom-focused patches that mask underlying problems. Understand WHY something fails before attempting to fix it.
The Four-Phase Framework
Phase 1: Root Cause Investigation
Before touching any code:
- Read error messages thoroughly - Every word matters
- Reproduce the issue consistently - If you can't reproduce it, you can't verify a fix
- Examine recent changes - What changed before this started failing?
- Gather diagnostic evidence - Logs, stack traces, state dumps
- Trace data flow - Follow the call chain to find where bad values originate
Root Cause Tracing Technique:
1. Observe the symptom - Where does the error manifest?
2. Find immediate cause - Which code directly produces the error?
3. Ask "What called this?" - Map the call chain upward
4. Keep tracing up - Follow invalid data backward through the stack
5. Find original trigger - Where did the problem actually start?
Key principle: Never fix problems solely where errors appear-always trace to the original trigger.
Phase 2: Pattern Analysis
- Locate working examples - Find similar code that works correctly
- Compare implementations completely - Don't just skim
- Identify differences - What's different between working and broken?
- Understand dependencies - What does this code depend on?
Phase 3: Hypothesis and Testing
Apply the scientific method:
- Formulate ONE clear hypothesis - "The error occurs because X"
- Design minimal test - Change ONE variable at a time
- Predict the outcome - What should happen if hypothesis is correct?
- Run the test - Execute and observe
- Verify results - Did it behave as predicted?
- Iterate or proceed - Refine hypothesis if wrong, implement if right
Phase 4: Implementation
- Create failing test case - Captures the bug behavior
- Implement single fix - Address root cause, not symptoms
- Verify test passes - Confirms fix works
- Run full test suite - Ensure no regressions
- If fix fails, STOP - Re-evaluate hypothesis
Critical rule: If THREE or more fixes fail consecutively, STOP. This signals architectural problems requiring discussion, not more patches.
Red Flags - Process Violations
Stop immediately if you catch yourself thinking:
- "Quick fix for now, investigate later"
- "One more fix attempt" (after multiple failures)
- "This should work" (without understanding why)
- "Let me just try..." (without hypothesis)
- "It works on my machine" (without investigating difference)
Warning Signs of Deeper Problems
Consecutive fixes revealing new problems in different areas indicates architectural issues:
- Stop patching
- Document what you've found
- Discuss with team before proceeding
- Consider if the design needs rethinking
Common Debugging Scenarios
Test Failures
1. Read the FULL error message and stack trace
2. Identify which assertion failed and why
3. Check test setup - is the test environment correct?
4. Check test data - are mocks/fixtures correct?
5. Trace to the source of unexpected value
Runtime Errors
1. Capture the full stack trace
2. Identify the line that throws
3. Check what values are undefined/null
4. Trace backward to find where bad value originated
5. Add validation at the source
"It worked before"
1. Use git bisect to find the breaking commit
2. Compare the change with previous working version
3. Identify what assumption changed
4. Fix at the source of the assumption violation
Intermittent Failures
1. Look for race conditions
2. Check for shared mutable state
3. Examine async operation ordering
4. Look for timing dependencies
5. Add deterministic waits or proper synchronization
Debugging Checklist
Before claiming a bug is fixed:
- Root cause identified and documented
- Hypothesis formed and tested
- Fix addresses root cause, not symptoms
- Failing test created that reproduces bug
- Test now passes with fix
- Full test suite passes
- No "quick fix" rationalization used
- Fix is minimal and focused
Success Metrics
Systematic debugging achieves ~95% first-time fix rate vs ~40% with ad-hoc approaches.
Signs you're doing it right:
- Fixes don't create new bugs
- You can explain WHY the bug occurred
- Similar bugs don't recur
- Code is better after the fix, not just "working"
Integration with Other Skills
- testing-patterns: Create test that reproduces the bug before fixing
Limitations
- Use this skill only when the task clearly matches its upstream source and local project context.
- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.
FAQ
Common questions
Discussion
Questions & comments · 0
Sign In Sign in to leave a comment.