| name | debugging |
| description | Quick diagnosis and fix for straightforward bugs and errors. Triggers on "fix this bug", "why is this broken", "this error keeps happening", "quick fix". NOT for complex multi-layer issues — use systematic-debugging instead. |
| allowed-tools | Read, Grep, Glob, Bash, Edit |
When to Use
- A single error message or stack trace needs diagnosis
- A test is failing with a clear error
- A quick bug fix is needed (off-by-one, typo, wrong import)
- Build or lint errors need resolution
When NOT to Use
- Complex bugs spanning multiple systems or layers — use
systematic-debugging
- Performance profiling or optimization — use
systematic-debugging
- Intermittent failures that need deep investigation — use
systematic-debugging
- Writing new features — use
implementation
Instructions
1. Collect Symptoms
Read the error message, stack trace, or failure description. Identify:
- The exact error text
- The file and line number (if available)
- What action triggered the error
2. Locate the Source
Use Grep to search for the error message in the codebase. Use Read to examine the file at the reported line. Check recent changes with git diff or git log --oneline -5 if the bug is a regression.
3. Form a Hypothesis
Based on the error and surrounding code, identify the most likely cause:
- Wrong variable name or type
- Missing null/undefined check
- Incorrect import or path
- Logic error (wrong operator, off-by-one)
- Missing dependency or configuration
4. Verify the Hypothesis
Read related code to confirm the hypothesis. Check:
- Does the function signature match the call site?
- Are all required fields present?
- Is the data flow correct from input to output?
5. Apply the Fix
Make the minimal change that fixes the root cause. Use Edit to modify the file. Do NOT refactor surrounding code — fix only the bug.
6. Verify the Fix
Run the failing test or command again to confirm the fix works. Check that no new errors were introduced.
Output
## Debug Report
**Issue:** [error description]
**Root Cause:** [what went wrong and why]
**Fix:** [what was changed, in which file]
**Verification:** [command run and result]
