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

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.