| name | debug |
| description | Systematic debugging workflow. Use for "debug", "fix bug", "not working", "error", "broken". |
| argument-hint | [issue description] |
| disable-model-invocation | true |
| user-invocable | true |
Debug Assistant
Systematic debugging workflow with documentation.
Workflow
1. Understand Problem
Ask user:
- Error message (exact text)?
- When does it occur? (always, sometimes, specific action)
- What changed recently?
- Console/network errors?
2. Create Debug Session
Write to .planning/DEBUG-LOG.md:
## Active Session
**Issue**: [description]
**Reported**: [date]
**Severity**: [Critical/High/Medium/Low]
### Error
[exact error text]
### Steps to Reproduce
1. [step]
2. [step]
3. Error occurs
### Expected vs Actual
- Expected: [what should happen]
- Actual: [what happens]
3. Investigate
Checklist:
bun run build
git diff HEAD~5
git log --oneline -10
Common causes by error type:
| Error | Check |
|---|
| "undefined" | Null handling, async timing |
| "Module not found" | Import paths, file exists |
| Type mismatch | Type definitions |
| RLS violation | Auth state, policies |
| Hydration | Client-only code in SSR |
Binary search:
- Does it work in simpler case?
- Does removing X fix it?
- Does adding X break it?
4. Document Findings
Update DEBUG-LOG.md:
### Attempt 1: Check RLS
- Theory: User lacks access
- Check: Ran query as user
- Result: Policy missing on budgets
- Conclusion: CONFIRMED
5. Fix
- Explain fix to user first
- Make minimal change
- Don't refactor while fixing
- Test immediately
6. Verify
bun run build
Fix Verified!
Issue: [description]
Root Cause: [what was wrong]
Fix: [what changed]
Files: src/lib/api.ts:45
7. Close Session
Update DEBUG-LOG.md:
## Solution
**Root Cause**: Missing null check
**Fix**: Added optional chaining
**Files**: src/lib/api.ts
**Lesson**: Add to RULES.md if pattern emerges
**Resolved**: [date]
Rules
- Don't guess - investigate systematically
- One change at a time
- Document everything
- Verify the fix works
- Minimal fixes, no refactoring
- Add to RULES.md if pattern emerges