Anthony Bordonaro

Debug with Context

Skill
claude-codedebuggingslash-commands

The default LLM behavior when shown an error is to immediately propose a fix. This usually addresses the symptom, not the cause. You apply the fix, a different error appears, and you're playing whack-a-mole.

This slash command forces Claude Code to gather full context — error message, stack trace, source files, recent changes — before proposing anything. The fix quality improves dramatically because the root cause is understood first.

The slash command

Save as .claude/commands/debug.md in your project:

# Debug with Context

Before proposing any fix:

1. Read the error message and full stack trace
2. Read the source file(s) referenced in the stack trace
3. Check for recent changes with `git diff` and `git log --oneline -10`
4. Identify the root cause — not just the symptom
5. Check if similar patterns exist elsewhere in the codebase that would have the same bug

Only after completing steps 1-5, propose a minimal fix that addresses the root cause. Explain:
- What caused the error
- Why this fix resolves it
- Whether other locations need the same fix

Then invoke with /debug in Claude Code followed by the error or description of the problem.

Why it works

The numbered steps create a forcing function. Without them, Claude jumps straight to "try changing X to Y." With them, it reads the stack trace, follows the imports, checks git history — and often discovers the real issue is two files away from where the error surfaced.

Step 3 (checking git history) is particularly valuable. Many bugs are introduced by recent changes, and git log --oneline -10 often reveals exactly which commit broke things.

Step 5 (checking for similar patterns) catches systemic issues. If a bug exists in one place, the same pattern likely exists elsewhere.

When to use it

  • Any runtime error with a stack trace
  • Test failures you don't immediately understand
  • Bugs that recur after "fixing" them (a sign you're treating symptoms)
  • Errors in code you didn't write

Tips

  • Include the full error output when invoking — don't summarize it. Stack traces contain information that summaries lose.
  • If Claude proposes a fix that feels like a patch (adding a null check, wrapping in try/catch), push back: "That addresses the symptom. What's the root cause?"
  • For test failures, add the failing test command to your invocation so Claude can reproduce it: /debug — npm test fails with: [error]
Back to AI Toolkit