boocode/data/skills/boocode/systematic-debugging/SKILL.md

name, description

name	description
systematic-debugging	Guided root-cause debugging. Use when encountering any bug, test failure, unexpected behavior, or performance problem. Enforces investigation before fixes.

Systematic Debugging

No fixes without root cause. Symptom fixes mask real bugs and waste time.

The Rule

Complete Phase 1 before proposing ANY fix. If you haven't investigated, you cannot fix.

Phase 1: Root Cause Investigation

1. Read error messages carefully. Stack traces, line numbers, error codes. Don't skip past them.
2. Reproduce consistently. Exact steps, every time. If not reproducible, gather more data instead of guessing.
3. Check recent changes. Git diff, recent commits, new deps, config changes, env differences.
4. Trace data flow. Where does the bad value originate? Trace backward through the call stack to the source. Fix at the source, not the symptom.
5. Multi-component systems: Before fixing, add diagnostic logging at each component boundary (what enters, what exits). Run once to locate the failing layer, THEN investigate that layer.

Phase 2: Pattern Analysis

1. Find working examples of similar code in the same codebase.
2. Compare working vs broken — list every difference.
3. If implementing a pattern, read the reference implementation completely, not skimmed.
4. Understand all dependencies, config, and assumptions.

Phase 3: Hypothesis and Testing

1. State one hypothesis clearly: "X is the root cause because Y."
2. Make the smallest possible change to test it. One variable at a time.
3. If it didn't work, form a NEW hypothesis. Don't stack more fixes on top.
4. After 3 failed fixes: STOP. Question the architecture, not the symptoms.

Phase 4: Implementation

1. Create a failing test case first (simplest reproduction).
2. Implement a single fix addressing the root cause.
3. Verify: test passes, no regressions, issue actually resolved.
4. If the fix doesn't work and you've tried 3+: the problem is architectural. Discuss before attempting more.

Red Flags — STOP and return to Phase 1

• "Quick fix for now, investigate later"
• "Just try changing X and see"
• "I don't fully understand but this might work"
• "One more fix attempt" after 2+ failures
• Proposing solutions before tracing data flow
• Each fix reveals a new problem in a different place

Apply This Skill

Use these tools to investigate before proposing changes:

• view_file to read error sites and suspect code paths
• grep to find all callers / references to the failing function
• find_files to locate related config, test fixtures, schema
• list_dir to understand the module layout around the bug

Report your Phase 1 findings (what you observed, what you traced, what you ruled out) before moving to Phase 3.