diff --git a/data/skills/boocode/systematic-debugging/SKILL.md b/data/skills/boocode/systematic-debugging/SKILL.md new file mode 100644 index 0000000..337961b --- /dev/null +++ b/data/skills/boocode/systematic-debugging/SKILL.md @@ -0,0 +1,61 @@ +--- +name: systematic-debugging +description: 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.