By name: systematic-debugging description: Systematic approach to debugging — follow these 8 steps when investigating bugs, errors, or unexpected behavior author: subinium user-invocable: true
Systematic Debugging
Follow these steps in strict order. Do not skip ahead.
Steps
1. Reproduce
- Get the exact error message and full stack trace
- Find the minimal reproduction case
- Confirm you can trigger the error consistently
2. Isolate
- Narrow down to the smallest failing unit
- Binary search: comment out half the code, check which half fails
- Check if the issue is in your code vs dependencies
3. Trace
- Follow data flow from input to the error point
- Log actual values at each step (don't assume)
- Check types at runtime, not just static analysis
4. Hypothesize
- Form at most 3 specific, testable theories
- Rank by likelihood
- Each hypothesis must predict a specific observable outcome
5. Test
- Test ONE hypothesis at a time
- Make the smallest possible change to verify
- If wrong, revert before testing the next hypothesis
6. Fix
- Apply the smallest correct fix
- Ensure the fix addresses the root cause, not the symptom
- Check for the same bug pattern elsewhere in the codebase
7. Verify
- Run the exact test that exposed the bug
- Run related tests to check for regressions
- Test edge cases around the fix
8. Prevent
- Add a regression test if one doesn't exist
- Consider if a type constraint or assertion could prevent recurrence
- Document if the root cause was non-obvious
Anti-Patterns (Never Do These)
- Shotgun debugging: changing multiple things at once
- Guessing without tracing actual values
- Fixing symptoms instead of root causes
- Skipping the verification step
- Adding try/catch to hide errors instead of fixing them