--- id: FradSer/dotclaude/systematic-debugging version: "328b515a" license: MIT install: manual updated: 2026-07-23 --- # systematic-debugging — Systematic Debugging enforces disciplined root-cause investigation before any code changes, using a 4-phase pipeline: evidence gathering, pattern comparison, hypothesis testing, and targeted fixes. It prevents the common failure mode of applying surface-level patches that mask underlying issues. Works with test failures, production bugs, performance problems, and build failures across any tech stack. Publisher: FradSer · Stars: 576 · Updated: 2026-07-23 Install (manual): `git clone https://github.com/FradSer/dotclaude` ## SKILL.md # Systematic Debugging ## Slash-command Usage Invoked via `/superpowers:systematic-debugging ""` or auto-loaded by other skills when bug-fix language is detected. **When invoked as a slash command**: capture `$ARGUMENTS` as the symptom statement and start at Phase 1 immediately. Do NOT write design documents or task files; the deliverable is `the fix + a test that catches the regression`, not a docs/plans/ folder. **Output discipline**: Report findings inline as you complete each phase. End with: (a) root cause one-liner, (b) fix diff summary, (c) regression test path. ## Recommended: run wrapped in `/goal` **Launch it under Claude Code's built-in `/goal`** (v2.1.139+) so the multi-turn hypothesis → test → fix investigation continues until the regression is actually fixed: ``` /goal "Claude has narrated the three-part completion output (root-cause one-liner, fix diff summary, regression-test path) with the regression test passing" /superpowers:systematic-debugging "" ``` `/goal` is a **user-typed outer wrapper** (a skill cannot enable it for itself mid-run), and its evaluator judges only what Claude narrates in the transcript — phrase the condition against narrated output (the printed test-run result, the three-part summary), never filesystem state. Full semantics and condition phrasing: `../../skills/references/goal-wrapper.md`. ## CRITICAL: Bail-Out Check (run before Phase 1) **Inspect `$ARGUMENTS` for "named root cause + named fix" signals. Bail out — skip the 4-phase pipeline, apply the fix and write a regression test directly — when ALL of these match:** - `$ARGUMENTS` names a specific root cause (file:line, config key, or specific value), AND - `$ARGUMENTS` names a specific corrective change ("change X to Y", "add the missing flag", "fix the typo"), AND - The fix is localized to a single file or a single string substitution Examples that bail out: - "cookie domain is `.foo.com`, should be `foo.com` — fix it" - "missing `await` at api.ts:42, add it" - "wrong env var name `DB_HOST` should be `DATABASE_HOST` in deploy.yaml" Examples that DO NOT bail out (proceed to Phase 1): - "tests fail in CI but pass locally" (symptom only, no root cause) - "this is slow" (no hypothesis) - "I think it's the cache, can you check?" (hypothesis without confirmed root cause) **Bail-out response (output verbatim, then apply the fix + a regression test that catches the bug):** > Detected named root cause and named fix. Skipping the 4-phase pipeline (calibrated for unknown root causes). Applying the fix and writing a regression test directly. To force the full pipeline, re-invoke as `/superpowers:systematic-debugging --force ""`. When the user passes `--force` (literal token in `$ARGUMENTS`), skip this bail-out and proceed to Phase 1 unconditionally. **Iron Law remains** for non-bail-out paths — the bail-out only fires when the user has *already done* the root-cause work and is handing Claude the conclusion. ## Overview **Core principle:** Root cause investigation must precede any fix attempt — random fixes waste time, mask underlying issues, and create new bugs. **Violating the letter of this process is violating the spirit of debugging.** ## CRITICAL: The Iron Law ``` NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST ``` Fixes cannot be proposed without completing Phase 1. Each phase MUST finish before the next begins. Violating this rule produces fix-attempts that mask root causes — the failure mode this skill exists to prevent. If at any point you find yourself proposing a fix without completed Phase 1 evidence, stop and return to Phase 1. ## When to Apply Applies to ANY technical issue: test failures, production bugs, unexpected behavior, performance problems, build failures. **Especially valuable when:** time pressure tempts guessing, a "quick fix" seems obvious, prior fixes failed, or the issue is not fully understood. Do NOT skip the process because the issue appears simple, time is tight, or urgency exists — see `./references/rationalizations-and-guardrails.md` for why each of those is a trap. ## The Four Phases ### Phase 1: Root Cause Investigation **Before attempting any fix:** 0. **Consult Memory** — this memory read-before step is skipped whenever the Bail-Out Check fires (symmetric with the bail-out skipping every other Phase-1-onward step): run `bash "${CLAUDE_PLUGIN_ROOT}/lib/docs-index.sh" list --kind memory --status active`, filter by symptom keywords, and Read the top 2-3 matches before step 1. 1. **Read Error Messages Carefully** — read stack traces completely; note line numbers, file paths, error codes. Messages and warnings often contain the solution. 2. **Reproduce Consistently** — identify exact steps and confirm the issue triggers reliably. If not reproducible, gather more data instead of guessing. 3. **Check Recent Changes** — git diff and recent commits, new dependencies, config changes, environmental differences. 4. **Gather Evidence in Multi-Component Systems** (CI -> build -> signing, API -> service -> database) — add diagnostic instrumentation before proposing fixes: ``` For EACH component boundary: - Log what data enters component - Log what data exits component - Verify environment/config propagation - Check state at each layer Run once to gather evidence showing WHERE it breaks THEN analyze evidence to identify failing component THEN investigate that specific component ``` Worked example (CI workflow → build → signing): `./references/root-cause-tracing.md` §Multi-Layer Instrumentation Example. 5. **Trace Data Flow** — when the error is deep in the call stack: identify where the bad value originates, determine what called it, keep tracing up until the source is found, fix at source not at symptom. Complete backward-tracing technique: `./references/root-cause-tracing.md`. ### Phase 2: Pattern Analysis **Pattern identification should precede any fix:** 1. **Find Working Examples** — locate similar working code in the same codebase. 2. **Compare Against References** — if implementing a pattern, read the reference implementation completely (every line, do not skim) before applying it. 3. **Identify Differences** — list every difference between working and broken code; do not dismiss small differences as irrelevant. 4. **Understand Dependencies** — other components this operation requires; settings, config, environment; assumptions made by the pattern. ### Phase 3: Hypothesis and Testing **Scientific method application:** 1. **Form Single Hypothesis** — state clearly and specifically: "X is the root cause because Y". 2. **Test Minimally** — smallest possible change, one variable at a time; do not fix multiple things simultaneously. 3. **Verify Before Continuing** — confirmed: proceed to Phase 4; not confirmed: form a new hypothesis. Do not add more fixes on top. 4. **When Understanding is Missing** — acknowledge it, research more, ask for help. ### Phase 4: Implementation **Fix the root cause, not the symptom:** 1. **Create Failing Test Case** — simplest possible reproduction; automated test if possible, one-off script if no framework. The test must exist before fixing. 2. **Implement Single Fix** — address the identified root cause, one change at a time; no "while I'm here" improvements, no bundled refactoring. 3. **Verify Fix** — test now passes? No other tests broken? Issue actually resolved? 4. **If Fix Doesn't Work** — stop and count attempted fixes. If < 3: return to Phase 1 and re-analyze with the new information. If >= 3: question the architecture. 5. **Architecture Questioning After 3+ Failed Fixes** — when each fix reveals a new shared-state/coupling problem elsewhere, requires "massive refactoring", or creates new symptoms, stop and question fundamentals: is the pattern sound? Is the approach continuing through inertia? Should the architecture be refactored instead of fixing symptoms? **Discuss with your human partner before attempting more fixes** — this is not a failed hypothesis, this is wrong architecture. 6. **Capture Memory (conditional — this skill's only `docs/` touchpoint, not a new phase or commit)** This step reuses the existing 3+ failed fixes trigger as its primary gate: firing that trigger runs upsert memory in the same commit as the fix, OR it fires independently on an explicit cross-cutting gotcha regardless of fix-attempt count; otherwise it is a no-op. On fire: write `docs/memory/_.md` (`category: pitfall` typically; `decision` if architecture questioning concluded a redesign), reusing the Inline Plan's six-line shape as `Fact`/`Why` material with `source: commit:`. Then run `bash "${CLAUDE_PLUGIN_ROOT}/lib/docs-index.sh" upsert memory docs/memory/ --status active --summary "" --category `, staged into the same commit as the fix + regression test — no separate commit, no extra deliverable. ## Complex Bugs: Inline Plan Summary (no file written) **For complex bugs, record a compact plan inline before any code change** — never a `docs/plans/` folder or `BUGFIX_PLAN.md` file (rationale: `./references/rationalizations-and-guardrails.md` §Why the Complex-Bug Plan Is Inline). The inline plan is the contract the skill holds itself to during Phase 2-4 and the audit surface the user reviews post-fix. ### When the Inline Plan Is Required A bug requires the inline-plan step before edits when ANY of these apply: multi-component involvement (multiple files/modules/subsystems), architecture implications (design, contracts, interfaces), multiple valid approaches, side-effect risk to unrelated functionality, refactoring beyond a minimal patch, or a root cause still unclear after Phase 1. ### Inline Plan Format After Phase 1 (Root Cause Investigation), record the plan **inline in your turn output** (not in a file) using this six-line shape, then proceed directly to Phase 2 with this plan as the contract: ``` ROOT CAUSE: FIX STRATEGY: FILES: TESTS: RISKS: "> ALTERNATIVES: ``` Do NOT pause for approval. The plan stays the contract through Phase 2-4; deviation requires re-running Phase 1 and recording a new six-line shape — do not silently mutate the fix mid-stream. If evidence is too thin to fill any line confidently, loop back to Phase 1 step 4 first; never paper over weak evidence with a vague line. **For simple bugs:** Continue with Phase 2-4 directly — no inline plan needed. ## Red Flags These mental patterns indicate process violation — return to Phase 1: - "Quick fix for now, investigate later" - "Just try changing X and see if it works" - "Add multiple changes, run tests" - "Skip the test, I'll manually verify" - "It's probably X, let me fix that" - "I don't fully understand but this might work" - "Pattern says X but I'll adapt it differently" - Proposing solutions before tracing data flow - **"One more fix attempt" (when already tried 2+)** - **Each fix reveals new problem in different place** **If 3+ fixes failed:** Question the architecture. **When the human partner redirects you** ("Is that not happening?", "Stop guessing", "We're stuck?"): return to Phase 1. Full signal list, plus the excuse-vs-reality table for every rationalization above: `./references/rationalizations-and-guardrails.md`. ## Quick Reference | Phase | Key Activities | Success Criteria | |-------|---------------|------------------| | **1. Root Cause** | Read errors, reproduce, check changes, gather evidence | Understand WHAT and WHY | | **2. Pattern** | Find working examples, compare | Identify differences | | **3. Hypothesis** | Form theory, test minimally | Confirmed or new hypothesis | | **4. Implementation** | Create test, fix, verify | Bug resolved, tests pass | ## When Process Reveals No Root Cause If systematic investigation reveals the issue is environmental, timing-dependent, or external: the process is complete — document what was investigated, implement appropriate handling (retry, timeout, error message), and add monitoring/logging for future investigation. **Note:** 95% of "no root cause" cases represent incomplete investigation. ## References - `./references/root-cause-tracing.md` - Backward tracing, multi-layer instrumentation example - `./references/rationalizations-and-guardrails.md` - Excuse table, partner signals, inline-plan rationale, impact numbers - `./references/defense-in-depth.md` - Add validation at multiple layers after finding root cause - `./references/condition-based-waiting.md` - Replace arbitrary timeouts with condition polling (example: `condition-based-waiting-example.ts`) - `./find-polluter.sh` - Bisect test suite to identify which test pollutes shared state - `../../skills/references/goal-wrapper.md` - `/goal` semantics and condition phrasing (shared) **Related skills:** - `superpowers:behavior-driven-development` - BDD principles including Gherkin scenarios for test design [View on SkillFed](https://skillfed.io/FradSer/dotclaude/systematic-debugging) · [View on GitHub](https://github.com/FradSer/dotclaude)