---

name: debug description: "Use when encountering bugs, test failures, or unexpected behavior. Hypothesis-driven debugging."

Systematic Debugging

Iron Law: NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.

The Process

Copy1. REPRODUCE  -> Trigger consistently
2. INVESTIGATE -> Gather evidence, trace data flow
3. HYPOTHESIZE -> Form ONE specific theory
4. TEST       -> Minimal change to verify
5. FIX        -> Address root cause
6. VERIFY     -> Confirm with test

Step 1: Reproduce

Copynpm test -- --testPathPattern="auth"
# Document: exact steps, expected vs actual, full error message

Cannot reproduce? Gather more data. Don't guess.

Step 2: Investigate

1. Read error messages completely - line numbers, stack traces, error codes
2. Check recent changes: git diff HEAD~5
3. Trace data flow: Add logging at component boundaries

Copyecho "=== Input to component: $INPUT ==="
# component does its thing
echo "=== Output: $OUTPUT ==="

Goal: Find WHERE it breaks, not just WHAT breaks.

Step 3: Hypothesize

Form ONE specific theory:

Copy"Token is null because login returns before API response completes."

Not: "Something's wrong with auth" (too vague)

Step 4: Test Hypothesis

Smallest possible change:

Copyconsole.log('Token before return:', token);

• Confirmed? Proceed to fix.
• Wrong? Form NEW hypothesis. Return to Step 3.

Step 5: Fix Root Cause

Step 6: Verify

Write test that fails before fix, passes after. Proves fix works.

Decision Criteria

Red Flags

• "Let me just try..." -> STOP. Investigate first.
• "Quick fix for now" -> Root cause first.
• Multiple fixes at once -> One hypothesis at a time.

Integration

Pairs with: tdd (write failing test), verification (prove fix works)