feat: add systematic-debugging slash command for BooChat + BooCoder
/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) <noreply@anthropic.com>
This commit is contained in:
61
data/skills/boocode/systematic-debugging/SKILL.md
Normal file
61
data/skills/boocode/systematic-debugging/SKILL.md
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user