superpowers-systematic-debugging

Systematic Debugging

Overview

Random fixes waste time, create new bugs. Quick patches mask real issue.

Core principle: ALWAYS find root cause before fixes. Symptom fixes = failure.

Break letter of process = break spirit of debugging.

The Iron Law

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

Phase 1 not done? Cannot propose fixes.

When to Use

ANY technical issue: test failures, production bugs, unexpected behavior, performance problems, build failures, integration issues.

ESPECIALLY when:

• Under time pressure (emergencies make guessing tempting)
• "Just one quick fix" seems obvious
• Already tried multiple fixes
• Previous fix didn't work
• Don't fully understand the issue

Don't skip when:

• Issue seems simple (simple bugs have root causes too)
• In a hurry (rushing guarantees rework)
• Manager wants it NOW (systematic beats thrashing)

The Four Phases

You MUST complete each phase before the next.

Phase 1: Root Cause Investigation

BEFORE attempting ANY fix:

1. Read Error Messages Carefully

   • Don't skip errors or warnings — often contain the exact solution
   • Read stack traces completely; note line numbers, file paths, error codes

2. Reproduce Consistently

   • Trigger it reliably? Exact steps?
   • Not reproducible → gather more data, don't guess

3. Check Recent Changes

   • What changed that could cause this? (git diff, recent commits, new deps, config)

4. Gather Evidence in Multi-Component Systems

   WHEN system has multiple components (CI → build → signing, API → service → database), BEFORE proposing fixes, add diagnostic instrumentation at each boundary:

   For EACH component boundary:
     - Log what data enters the component
     - Log what data exits the component
     - Verify environment/config propagation
   Run once to gather evidence showing WHERE it breaks
   THEN investigate that specific component
   

   Example (multi-layer system):

   echo "=== Secrets available in workflow ==="
   echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
   echo "=== Env vars in build script ==="
   env | grep IDENTITY || echo "IDENTITY not in environment"
   echo "=== Keychain state ==="
   security find-identity -v
   

   This reveals which layer fails (secrets → workflow ✓, workflow → build ✗).