systematic-debugging

What this skill does

# Systematic Debugging

## Slash-command Usage

Invoked via `/superpowers:systematic-debugging "<symptom>"` or auto-loaded by other skills (BDD, brainstorming) when bug-fix language is detected.

**When invoked as a slash command**: capture `$ARGUMENTS` as the symptom statement, then start at Phase 1 (Root Cause Investigation) immediately. Debugging is iterative within a single session, not phase-driven. 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.

## 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 proceed with direct edit + write 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: NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST. The bail-out only fires when the user has *already done* the root cause work and is handing the conclusion to Claude.

## Overview

Random fixes waste time and create new bugs. Quick patches mask underlying issues.

**Core principle:** Root cause investigation must precede any fix attempt. Symptom fixes represent process failure.

**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

Systematic debugging applies to ANY technical issue:
- Test failures
- Bugs in production
- Unexpected behavior
- Performance problems
- Build failures
- Integration issues

**Especially valuable when:**
- Time pressure creates temptation to guess
- "Quick fix" seems obvious
- Multiple fixes have already been attempted
- Previous fixes failed
- Issue is not fully understood

**Process should not be skipped even when:**
- Issue appears simple (simple bugs have root causes too)
- Time is tight (systematic approach is faster than thrashing)
- Urgency exists (investigation is faster than rework)

## The Four Phases

Each phase must be completed before proceeding to the next.

### Phase 1: Root Cause Investigation

**Before attempting any fix:**

1. **Read Error Messages Carefully**
   - Error messages and warnings often contain solutions
   - Read stack traces completely
   - Note line numbers, file paths, error codes

2. **Reproduce Consistently**
   - Determine if the issue triggers reliably
   - Identify exact steps
   - Confirm reproducibility
   - 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**

   **For systems with multiple components (CI -> build -> signing, API -> service -> database):**

   Diagnostic instrumentation should be added 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
   ```

   **Multi-layer system example:**
   ```bash
   # Layer 1: Workflow
   echo "=== Secrets available in workflow: ==="
   echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"

   # Layer 2: Build script
   echo "=== Env vars in build script: ==="
   env | grep IDENTITY || echo "IDENTITY not in environment"

   # Layer 3: Signing script
   echo "=== Keychain state: ==="
   security list-keychains
   security find-identity -v

   # Layer 4: Actual signing
   codesign --sign "$IDENTITY" --verbose=4 "$APP"
   ```

   This reveals which layer fails.

5. **Trace Data Flow**

   **When error is deep in call stack:**

   See `./references/root-cause-tracing.md` for the complete backward tracing technique.

   **Quick approach:**
   - Identify where bad value originates
   - Determine what called this with bad value
   - Continue tracing up until source is found
   - Fix at source, not at symptom

### Phase 2: Pattern Analysis

**Pattern identification should precede any fix:**

1. **Find Working Examples**
   - Locate similar working code in same codebase
   - Identify working code similar to what's broken

2. **Compare Against References**
   - If implementing a pattern, read reference implementation completely
   - Read every line, do not skim
   - Understand pattern fully before applying

3. **Identify Differences**
   - List every difference between working and broken code
   - Do not dismiss small differences as irrelevant

4. **Understand Dependencies**
   - Other components required by this operation
   - Settings, config, environment needed
   - Assumptions made by the pattern

### Phase 3: Hypothesis and Testing

**Scientific method application:**

1. **Form Single Hypothesis**
   - State clearly: "X is the root cause because Y"
   - Be specific, not vague

2. **Test Minimally**
   - Make smallest possible change to test hypothesis
   - One variable at a time
   - Do not fix multiple things simultaneously

3. **Verify Before Continuing**
   - If hypothesis confirmed: proceed to Phase 4
   - If not confirmed: form new hypothesis
   - Do not add more fixes on top

4. **When Understanding is Missing**
   - Acknowledge lack of understanding
   - Ask for help
   - Research more

### Phase 4: Implementation

**Fix the root cause, not the symptom:**

1. **Create Failing Test Case**
   - Simplest possible reproduction
   - Automated test if possible
   - One-off test script if no framework
   - 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
   - Count attempted fixes
   - If < 3: Return to Phase 1, re-analyze with new information
   - If >= 3: Question architecture

5. **Architecture Questioning After 3+ Failed Fixes**

   **Patterns indicating architectural problem:**
   - Each fix reveals new shared state/coupling/problem in different p