superpowers-systematic-debug

Files (1)

• SKILL.md

SKILL.md (first lines)

# Superpowers: Systematic Debugging Skill

Use this skill when encountering test failures, unexpected application errors, runtime exceptions, or broken behavior.

## Core Rules
1. **Never guess**: Every code edit during debugging must be justified by empirical log evidence or root-cause tracebacks.
2. **Never mask symptoms**: Do not swallow exceptions, return dummy nulls, or change assertion expectations to hide a bug.

## The 4-Phase Debugging Process

```mermaid
graph TD
    A["Phase 1: Evidence Gathering"] --> B["Phase 2: Hypothesis Formulation"]
    B --> C["Phase 3: Controlled Isolation"]
    C --> D["Phase 4: Root Cause Fix & Verification"]
```

### Phase 1: Evidence Gathering
- Read complete un-truncated error logs and tracebacks.
- Identify exact failing line, error type, and execution context.
- Inspect state variables leading up to the failure.

### Phase 2: Hypothesis Formulation
- Formulate 1 to 3 specific, testable hypotheses for why the failure occurs.
- Rank hypotheses by likelihood based on code inspection and error logs.

### Phase 3: Controlled Isolation
- Isolate the failing component in a minimal test or script.
- Test hypotheses one by one without modifying unrelated business logic.

### Phase 4: Root Cause Fix & Verification
- Apply the fix addressing the root cause at the upstream source.
- Re-run the full test suite to verify the issue is resolved and no regressions were introduced.

From karim-embarek/superpowers-antigravity, MIT.

More from karim-embarek/superpowers-antigravity