debugging

1. Capture exact repro, scope, and recent changes
2. Isolate components/files; trace path to failure
3. Research exact error; check official docs
4. Compare failing vs working patterns; form a testable hypothesis
5. Verify with minimal test; apply minimal fix across all instances; validate

Use debugging when:

• A bug has no obvious cause or has been "fixed" before but returned
• Error messages are unclear or misleading
• Multiple attempted fixes have failed
• The issue might affect multiple locations in the codebase
• Understanding the root cause is critical for proper resolution

Skip this skill for:

• Simple syntax errors with obvious fixes
• Trivial typos or missing imports
• Well-understood, isolated bugs with clear solutions

Based on documented failures in AI debugging, explicitly avoid:

1. Circular Reasoning: Never propose the same fix twice without learning why it failed
2. Premature Victory: Always verify fixes were actually implemented and work
3. Pattern Amnesia: Maintain awareness of established code patterns throughout the session
4. Context Overload: Use the 50% rule - restart conversation when context reaches 50%
5. Symptom Chasing: Resist fixing error messages without understanding root causes
6. Implementation Before Understanding: Never jump to code changes before examining existing patterns

• Understand: capture exact repro, scope, and recent changes
• Narrow: isolate components/files; trace path to failure
• Discover: research exact error (WebSearch → Parallel Search, Context7:get-library-docs)
• Examine: compare against known-good patterns in the codebase
• Reason: use SequentialThinking:process_thought and 5 Whys to reach root cause
• Synthesize: write a falsifiable hypothesis with predictions
• Test: add logs/tests to confirm the mechanism
• Apply: minimal fix for root cause, across all occurrences, following patterns
• Note: record insights, warnings, decisions
• Document: update comments/docs/tests as needed

Use TodoWrite to track debugging progress through the UNDERSTAND checklist:

1. At start: Create todos for each applicable step:

```

☐ U - Capture exact repro and scope

☐ N - Isolate failing component

☐ D - Research error message

☐ E - Compare with working patterns

☐ R - Root cause analysis (5 Whys)

☐ S - Write falsifiable hypothesis

☐ T - Verify with minimal test

☐ A - Apply fix across all occurrences

☐ N - Record insights

☐ D - Update docs/tests

```

1. During debugging: Mark steps in_progress → completed as you work through them

1. When stuck: TodoWrite makes it visible which step is blocked - helps identify if you're skipping steps or going in circles

1. Skip steps only if: Bug is simple enough that checklist is overkill (see "Skip this skill for" above)

• Know exact text/symbol? → grep
• Need conceptual/semantic location? → codebase_search
• Need full file context? → read_file
• Unfamiliar error/behavior? → Context7:get-library-docs, then WebSearch → Parallel Search
• Complex multi-hypothesis analysis? → SequentialThinking:process_thought

• Restart at ~50% context usage to avoid degraded reasoning
• Before restart: summarize facts, hypothesis, ruled-outs, next step
• Start a fresh chat with just that summary; continue

IF same fix proposed twice → Stop; use SequentialThinking:process_thought

IF error is unclear → Research via WebSearch → Parallel Search; verify with docs

IF area is unfamiliar → Explore with codebase_search; don't guess

IF fix seems too easy → Confirm it addresses root cause (not symptom)

IF context is cluttered → Restart at 50% with summary

IF multiple hypotheses exist → Evaluate explicitly (evidence for/against)

IF similar code works → Find and diff via codebase_search/read_file

IF declaring success → Show changed lines; test fail-before/pass-after

IF fix spans multiple files → Search and patch all occurrences

IF library behavior assumed → Check Context7:get-library-docs

Before declaring a bug fixed, verify:

• [ ] Root cause identified and documented
• [ ] Fix addresses cause, not symptom
• [ ] All occurrences fixed (searched project-wide)
• [ ] Follows existing code patterns
• [ ] Original symptom eliminated
• [ ] No regressions introduced
• [ ] Tests/logs verify under relevant conditions
• [ ] Docs/tests updated (comments, docs, regression tests)

• reference/root-cause-framework.md
• reference/antipatterns.md