muyen Systematic Debugging Skill
Apply structured 4-phase debugging to find root causes, not just symptoms.
When to Activate
This skill should activate when:
- User reports a bug or unexpected behavior
- Error messages or stack traces appear
- Tests are failing
- User says "fix", "debug", "broken", "not working", "issue"
- Behavior differs from expected
4-Phase Debugging Process
Phase 1: REPRODUCE
Before fixing anything:
1. Understand the expected behavior
2. Understand the actual behavior
3. Find reliable reproduction steps
4. Identify the exact error/symptom
Questions to answer:
- What should happen?
- What actually happens?
- Can I reproduce it consistently?
- What are the exact steps?
Phase 2: ISOLATE
Narrow down the problem:
1. Find the smallest reproduction case
2. Identify which component/layer fails
3. Check recent changes (git log, git diff)
4. Add logging/debugging to trace execution
Techniques:
- Binary search through code changes
- Add strategic logging
- Comment out code sections
- Test with minimal input
Phase 3: IDENTIFY ROOT CAUSE
Find the actual cause, not symptoms:
1. Follow the data flow
2. Check assumptions
3. Verify inputs/outputs at each step
4. Ask "why" 5 times
Common root causes:
| Symptom | Likely Root Cause |
|---|---|
| 404 on API | Route not registered |
| Type mismatch | Wrong type conversion |
| Null pointer | Uninitialized variable |
| Race condition | Missing synchronization |
| Auth failure | Token/session expired |
Phase 4: FIX AND VERIFY
Fix properly:
1. Write a test that reproduces the bug
2. Implement the fix
3. Verify the test passes
4. Check for similar issues elsewhere
5. Prevent regression
Debugging Commands
Backend (Go)
# Run with verbose logging
go run ./cmd/api/main.go
# Run specific test with verbose output
go test -v -run TestName ./...
# Add debug logging
zap.L().Debug("checkpoint", zap.Any("data", data))
iOS (Swift)
// Debug print (visible in Xcode console)
#if DEBUG
print("DEBUG: \(variable)")
#endif
Android (Kotlin)
// Debug logging
Log.d("TAG", "Debug: $variable")
Process
- Don't guess - Reproduce first
- Don't fix symptoms - Find root cause
- Verify assumptions - Check each step
- Test the fix - Write regression test
- Check for similar issues - Fix all instances
Output Format
## Bug Analysis
**Symptom**: [what user reported]
**Reproduction**: [steps to reproduce]
### Investigation
- [ ] Reproduced: [yes/no]
- [ ] Isolated to: [component/file]
- [ ] Root cause: [actual cause]
### Fix
- **File**: [file:line]
- **Change**: [what was changed]
- **Test**: [test that prevents regression]
### Verification
- [ ] Original issue fixed
- [ ] No new issues introduced
- [ ] Similar code checked