name: debug
description: "Systematically debugs issues using structured diagnosis — reproduce, isolate, identify root cause, and fix. Use when facing bugs, errors, unexpected behavior, or failing tests."
argument-hint: "[error message, symptom, or file:line]"
allowed-tools: Read, Grep, Glob, Bash, Edit
Structured Debugging
Recent Changes
!git log --oneline -10 2>/dev/null !git diff --stat HEAD~3 2>/dev/null
Debugging Process
- What is the symptom? — Error message, unexpected behavior, crash, performance issue
- When did it start? — Check recent commits:
git log --oneline -20 - Is it reproducible? — Always, sometimes, only in certain environments?
- What changed? — Recent code changes, dependency updates, config changes
Step 2: Read the Error
If there's an error message or stack trace:
- Read the full error message — don't skip parts
- Identify the origin — which file and line threw the error?
- Trace the call stack — how did execution reach that point?
- Check for root cause vs symptom — the first error in the chain is usually the cause
Step 3: Isolate the Problem
Use a binary search strategy:
- Narrow the scope: Is the issue in the frontend, backend, database, or external service?
- Check inputs: Are the inputs to the failing function correct?
- Check dependencies: Are all required services/modules available?
- Check state: Is the application/database in the expected state?
- Check environment: Are env vars, configs, and versions correct?
Step 4: Common Debugging Patterns
#### "It works on my machine"
- Check environment variables
- Check dependency versions (lock file differences)
- Check OS/runtime version differences
- Check file path separators (Windows vs Unix)
- Check timezone/locale differences
#### "It worked yesterday"
git bisect to find the breaking commit- Check for dependency updates (lock file changes)
- Check for infrastructure/config changes
- Check for data changes in the database
#### "It works sometimes"
- Race condition — look for shared mutable state
- Timing issue — look for missing awaits, unhandled promises
- Resource exhaustion — connections, file handles, memory
- External dependency flakiness — network, API rate limits
#### "It's slow"
- Profile before guessing — use the project's profiling tools
- Check for N+1 queries
- Check for missing indexes
- Check for synchronous blocking in async code
- Check for unnecessary re-computation
Step 5: Fix and Verify
- Implement the minimal fix
- Verify the fix resolves the original issue
- Check for regressions — run related tests
- Add a test that would have caught this bug
- Document the root cause in the commit message
Step 6: Prevent Recurrence
- Should there be input validation to catch this earlier?
- Should there be a test for this scenario?
- Should there be monitoring/alerting for this condition?
- Should the error message be improved for faster debugging next time?
Rules
- Don't guess and check randomly — use a systematic approach
- Read the error message — it usually tells you exactly what's wrong
- Check the obvious first — typos, missing imports, wrong file paths
- One change at a time — so you know what fixed it
- Always add a regression test for the bug you fixed