From 6d24726c3a4aa63650b0dd6b02d0cc0d68fce020 Mon Sep 17 00:00:00 2001 From: indifferentketchup Date: Sat, 30 May 2026 20:37:51 +0000 Subject: [PATCH] feat: add systematic-debugging slash command for BooChat + BooCoder MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit /data/skills/boocode/systematic-debugging/SKILL.md — guided root-cause debugging methodology (investigate before fixing). Available as /systematic-debugging in both BooChat and BooCoder slash menus via the shared /api/skills endpoint. Co-Authored-By: Claude Opus 4.8 (1M context) --- .../boocode/systematic-debugging/SKILL.md | 61 +++++++++++++++++++ 1 file changed, 61 insertions(+) create mode 100644 data/skills/boocode/systematic-debugging/SKILL.md 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.