Debug

Debug

Investigate and fix the issue described in "$ARGUMENTS" using systematic root cause analysis. No guessing — find the cause before attempting fixes.

Prerequisites

None — this is a utility skill that can run anytime a bug is encountered.

Process

Phase 1: Investigation

1. Read error messages carefully:

   • Read the full error output, stack trace, and any warnings
   • Note file paths, line numbers, and error codes
   • Don't skip past errors — they often contain the solution

2. Reproduce the issue:

   • Identify the exact steps to trigger the bug
   • Can it be triggered reliably?
   • If not reproducible, gather more data before proceeding

3. Check recent changes:

   • What changed recently that could cause this? (git log, git diff)
   • New dependencies, config changes, environment differences?

Phase 2: Analysis

4. Trace the data flow:

   • Where does the bad value originate?
   • Trace backward through the call stack to the source
   • Fix at the source, not at the symptom

5. Find working examples:

   • Is there similar code that works correctly?
   • What's different between working and broken?

Phase 3: Hypothesis

6. Form a single hypothesis:

   • State clearly: "I think X is the root cause because Y"
   • Be specific, not vague

7. Test minimally:

   • Make the smallest possible change to test the hypothesis
   • One variable at a time
   • If it doesn't work, form a NEW hypothesis — don't pile fixes

Phase 4: Fix

8. Write a failing test that reproduces the bug

9. Implement the fix — address the root cause, not the symptom

10. Verify:

    • The failing test now passes
    • No other tests broke
    • The original issue is resolved

11. Commit the fix with a clear message explaining what was wrong and why

Output

Present findings to the user:

• What the root cause was
• What was changed to fix it
• The commit hash
• Any related issues discovered during investigation