| name | debugging |
| description | A systematic, evidence-based approach to finding and fixing bugs. |
Skill: Structured Debugging
Category: Core Engineering
Priority: Critical
Description
A systematic, evidence-based approach to finding and fixing bugs.
Purpose
Eliminate guesswork. Fix root causes, not symptoms.
Trigger
Use this skill when:
- A bug is reported
- Tests fail unexpectedly
- Behavior does not match expectations
- Performance degrades
Context
- Error logs and stack traces
- Recent code changes
- Environment differences
- Reproduction steps
Workflow
- Reproduce - Can you make it fail consistently?
- Isolate - Binary search: comment out half the code. Which half fails?
- Hypothesize - Form a theory about the root cause.
- Test Hypothesis - Add logging or use a debugger to confirm.
- Fix Root Cause - Address the source, not the symptom.
- Verify Fix - Confirm the bug is gone AND no new bugs introduced.
- Add Regression Test - Ensure this bug never returns.
- Document - Update knowledge base if the fix reveals a pattern.
Examples
Good
Bug: Users see 500 error on checkout
1. Reproduce: Confirmed on staging with user ID 12345
2. Isolate: Error occurs in payment service, not cart service
3. Hypothesize: Null pointer when user has no saved cards
4. Test: Add debug log -> confirmed null `cards` array
5. Fix: Add null check before iterating cards
6. Verify: Checkout works for user 12345 AND existing users with cards
7. Regression test: Unit test for null cards scenario added
8. Document: Added to anti-patterns: "Always null-check before iteration"
Bad
Bug: 500 error
Fix: Added try-catch to swallow the error.
Anti-patterns
- Fixing symptoms with try-catch
- Skipping reproduction
- Not adding regression tests
- Debugging without logs
Verification
References