OpenSkillIndex← back to search
claude-code

Marketplace systematic-debugging

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

install
source · Clone the upstream repo
git clone https://github.com/aiskillstore/marketplace
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/aiskillstore/marketplace "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/dmjgilbert/systematic-debugging" ~/.claude/skills/aiskillstore-marketplace-systematic-debugging-6b438f && rm -rf "$T"
manifest: skills/dmjgilbert/systematic-debugging/SKILL.md
source content

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