| name | debug-protocol |
| description | A systematic, scientific debugging workflow to isolate and fix bugs efficiently without guessing. |
Debug Protocol (The Fixer 🕵️♂️)
Stop guessing. Follow the scientific method to solve bugs definitively.
Phase 1: Reproduction & Isolation
Goal: Make it fail reliably.
- Analyze the Error: Read the entire stack trace. Identify the EXACT file and line number.
- Create Reproduction Step: Can you trigger it with a curl command? A specific UI click? A unit test?
- If you can't reproduce it, you can't fix it.
- Isolate Environment: Is it a data issue? A code issue? A config issue?
- Binary Search: Comment out half the code/modules to find the culprit.
Phase 2: Root Cause Analysis (RCA)
Goal: Understand WHY it fails.
- Trace the Data: Log the state at entry, middle, and exit points of the suspicious function.
- Challenge Assumptions: "This variable should be an array" -> Is it actually?
- Check Recent Changes: Did this work yesterday? What changed? (
git log)
Phase 3: The Fix & Verification
Goal: Fix it and ensure it stays fixed.
- Apply Minimal Fix: Don't refactor the whole system. Fix the specific bug first.
- Verify Reproduction: Run the reproduction step from Phase 1. It must pass now.
- Regression Test: Run related tests to ensure you didn't break anything else.
- prevent recurrence: Can you add a type guard, validaton, or test case to prevent this forever?
