systematic-debugginglisted

# 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 syn