systematic-debugging

DMJGilbert's avatarfrom DMJGilbert

Four-phase root cause investigation before attempting fixes. Use when debugging bugs, test failures, or unexpected behavior.

⭐1stars🔀0forks📁View on GitHub🕐Updated Dec 21, 2025
[Debugging]

When & Why to Use This Skill

The Systematic Debugging skill implements a rigorous, four-phase root cause investigation framework designed to eliminate trial-and-error coding. By prioritizing evidence-based analysis—including pattern recognition, hypothesis testing, and data flow tracing—this skill ensures that software fixes address the underlying issue rather than just masking symptoms, significantly improving code reliability and developer productivity.

Use Cases

  • Case 1: Resolving intermittent test failures or 'flaky' tests by performing backward data flow tracing to identify where invalid states originate.
  • Case 2: Investigating complex production bugs where multiple system components interact, using pattern analysis to compare differences between working and broken environments.
  • Case 3: Validating architectural integrity when repeated 'quick fixes' fail, helping teams determine if a deeper refactor is required instead of further patching.
  • Case 4: Implementing Test-Driven Development (TDD) for bug fixes by creating failing test cases based on verified root causes before writing any solution code.
namesystematic-debugging
descriptionFour-phase root cause investigation before attempting fixes. Use when debugging bugs, test failures, or unexpected behavior.

Systematic Debugging

ALWAYS find root cause before attempting fixes. Symptom fixes are failure.

When to Use

  • Encountering bugs or test failures
  • Unexpected behavior in code
  • Before proposing any fix

The Four Phases

Phase 1: Root Cause Investigation

Before proposing any solution:

  1. Read error messages thoroughly - Don't skip warnings or stack traces; they often contain exact solutions
  2. Reproduce consistently - Verify you can trigger the issue reliably with documented steps
  3. Check recent changes - Examine git diff, dependencies, and configuration modifications
  4. Gather diagnostic evidence - In multi-component systems, add instrumentation at component boundaries
  5. Trace data flow - Backward trace from the error to find where bad values originate

Phase 2: Pattern Analysis

Establish the pattern before fixing:

  1. Locate similar working code in the codebase
  2. Read reference implementations completely (not skimmed)
  3. List every difference between working and broken code
  4. Understand all dependencies and assumptions

Phase 3: Hypothesis Testing

Apply scientific method:

  1. State your hypothesis clearly: "I believe X is failing because Y, evidenced by Z"
  2. Test with the smallest possible change
  3. Change only ONE variable at a time
  4. Verify results before proceeding

Phase 4: Implementation

Fix the root cause systematically:

  1. Create a failing test case first (TDD)
  2. Implement a single fix addressing only the root cause
  3. Verify the fix resolves the issue without breaking other tests
  4. If fix doesn't work, return to Phase 1

Red Flags - STOP Immediately

  • Proposing fixes without understanding the issue
  • Attempting multiple simultaneous changes
  • Assuming problems without verification
  • Skipping evidence gathering
  • Making "quick fixes" before investigation

When 3+ Fixes Fail

STOP. This signals an architectural problem, not a fixable bug:

  1. Do not attempt another fix
  2. Return to Phase 1
  3. Question whether the underlying pattern/design is sound
  4. Ask: "Should we refactor architecture vs. continue fixing symptoms?"

Random fixes waste time and create new bugs. Quick patches mask underlying issues.

Results

Systematic approach: 15-30 minutes to resolution with 95% first-time success vs. Trial-and-error: 2-3 hours of thrashing with 40% success and new bugs introduced