dmitryprg-ai Bug Fix Protocol
Principle: Fix the root cause, not the symptom.
Patching symptoms creates a growing pile of workarounds that eventually become harder to maintain than the original bug. Every bug is a signal that something in the system's design allowed it to happen.
Workflow
- STOP — Pause at the error. Rushing to fix without understanding causes more damage.
- CAPTURE — Record full error context (command, output, file, action).
- ANALYZE — Apply 5 Whys to find root cause (see below).
- FIX — Apply minimal patch to address root cause, not symptom.
- VERIFY — Confirm the exact same trigger no longer produces the error.
- PREVENT — Add protection against recurrence (test, validation, guard).
Error Capture
## ERROR CAPTURED
**Command:** [what caused the error]
**Error Output:** [FULL output, don't truncate]
**Context:** File: [file], Action: [what I was doing]
5 Whys Root Cause Analysis
Dig at least 5 levels deep. Surface-level fixes are temporary.
**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 |
| TypeError | Wrong data type or null | Check actual types at runtime |
| 500 Error | Unhandled exception | Add error handling + log |
| Connection refused | Service not running | Start/restart service |
| 401 Unauthorized | Missing auth headers | Check Basic Auth + Session |
What to avoid
- Silent catches:
try/catch {}hides the root cause and makes the same bug resurface later in a harder-to-debug location. - Multiple fixes at once: change one thing at a time so you know exactly which change resolved the issue.
- Workarounds without docs: if you must work around an issue temporarily, document why and create a follow-up task.
- Ignoring recurring errors: if the same error appears twice, it needs a systemic fix, not another patch.
Success Criteria
- The same command that caused the error now works
- Root cause is addressed, not just the symptom
- No new errors introduced