systematic-debugging

name	systematic-debugging
description	Diagnoses a reported bug, error, test failure, or unexpected behavior through a 4-phase root-cause analysis before any code changes.
argument-hint	<bug description or symptom>
user-invocable	true
disable-model-invocation	true
allowed-tools	["Read","Grep","Glob","Edit","Write","Agent","Bash(git:*)","Bash(npm:*)","Bash(pnpm:*)","Bash(uv:*)","Bash(pip:*)","Bash(pytest:*)","Bash(python:*)","Bash(python3:*)","Bash(go:*)","Bash(cargo:*)","Bash(mvn:*)","Bash(gradle:*)","Bash(rspec:*)","Bash(bundle:*)","Bash(test:*)","Bash(${CLAUDE_PLUGIN_ROOT}/skills/systematic-debugging/find-polluter.sh:*)","Bash(${CLAUDE_PLUGIN_ROOT}/lib/docs-index.sh:*)"]

Systematic Debugging

Slash-command Usage

Invoked via /superpowers:systematic-debugging "<symptom>" 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 "<symptom>"

/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 "<symptom>".

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/<category>_<slug>.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:<short-sha>. Then run bash "${CLAUDE_PLUGIN_ROOT}/lib/docs-index.sh" upsert memory docs/memory/<path> --status active --summary "<one-line>" --category <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: <one-line summary from Phase 1 evidence>
FIX STRATEGY: <what change resolves the cause, in one sentence>
FILES: <comma-separated paths that will be modified>
TESTS: <regression test path(s) + scenario name>
RISKS: <one line — side effects, blast radius, or "low: localized to <subsystem>">
ALTERNATIVES: <one line — rejected approaches + why>

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