| name | bugfix |
| description | Fix bugs, errors, exceptions, and unexpected behavior. Use when debugging, fixing errors, handling crashes, or when user mentions bug, error, broken, not working, crash, exception, 500 error, Application error. Uses 5 Whys Root Cause Analysis. |
Bug Fix Protocol
Principle: FIX ROOT CAUSE, NOT SYMPTOM.
Workflow
- STOP -- Pause at the error
- CAPTURE -- Record all error information
- ANALYZE -- 5 Whys to find root cause
- FIX -- Minimal patch for root cause
- VERIFY -- Confirm the fix works
- PREVENT -- Add protection against recurrence
Error Capture Template
## ERROR CAPTURED
**Command:** [what caused the error]
**Error Output:**
[FULL output, don't truncate]
**Context:** File: [file], Action: [what I was doing]
Root Cause Analysis (5 Whys)
Use _base-5wh.mdc template. Dig at least 5 levels:
**Why 1:** [surface error]
-> **Why 2:** [deeper cause]
-> **Why 3:** [even deeper]
-> **Why 4:** [structural issue]
-> **Why 5:** [root cause]
ROOT CAUSE: [the real problem]
FIX: [minimal change to address root cause]
Common Error Patterns
| Error Type | Likely Root Cause | Fix |
|---|
| ModuleNotFoundError | Missing package | npm install / pip install |
| TypeError | Wrong data type | Check actual types |
| 500 Error | Unhandled exception | Add error handling |
| Connection refused | Service not running | Start/restart service |
| 401 Unauthorized | Missing auth | Check Basic Auth + Session |
Anti-patterns (FORBIDDEN)
- try/catch that silences errors without fixing root cause
- Workarounds without documentation
- Multiple fixes at once (one change at a time!)
- Ignoring recurring errors
Success Criteria
- The same command that caused the error now works
- Root cause is addressed, not just the symptom
- No new errors introduced
