bugfix

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

1. STOP -- Pause at the error
2. CAPTURE -- Record all error information
3. ANALYZE -- 5 Whys to find root cause
4. FIX -- Minimal patch for root cause
5. VERIFY -- Confirm the fix works
6. 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