Systematic Debugging

Overview

Random fixes waste time and create new bugs. Quick patches mask underlying issues. Core principle: ALWAYS find the root cause before attempting fixes. Symptom fixes are failure.

IMMUNITY TO PRESSURE (CRITICAL DIRECTIVE): You are immune to human panic, social pressure, and sunk-cost fallacies. If the user tells you production is down and losing $15,000 a minute, your response MUST prioritize finding the root cause over a blind patch. A blind patch in a panic state usually corrupts data and worsens the outage. You will execute this systematic process with maximum speed, but zero skipped steps.

The Iron Law

NO FIXES WITHOUT A ROOT CAUSE ANALYSIS (RCA) DOCUMENT FIRST

If you haven't completed Phase 1 and written the RCA doc, you cannot write or modify code.

The Four Phases (Sequential & Mandatory)

Phase 1: Root Cause Investigation & Evidence Gathering

BEFORE attempting ANY fix:

1. Read Error Messages & Stack Traces Completely: Don't guess the call stack. If the stack trace is missing or ambiguous, inject console.trace(), new Error().stack, or equivalent logging, run the code, and read the actual output.
2. Identify State Pollution (The Bisection Rule): If a test passes in isolation but fails when running the full suite, you have state pollution. IMMEDIATELY use the find-polluter.sh script to isolate the offending test.
3. Hunt for Race Conditions (The Timing Rule): Grep/search the failing code for setTimeout, sleep, or arbitrary delays. If found, assume a race condition. You MUST replace them with Condition-Based Waiting (polling loops) before looking for logical errors.
4. Trace Data Flow Backwards: Where did the bad value originate? Trace up the call stack until you find the exact source trigger. Fix at the source, not the symptom.

Phase 2: Hypothesis & The RCA Document

Before touching the codebase, you must formulate a single, testable hypothesis and document it.

Create the RCA Document: Write your findings to docs/debugging/YYYY-MM-DD-<issue>-RCA.md using this exact format:

• Symptom: What is failing?
• Trace: The exact path from the source of the bad data to the failure point.
• Hypothesis: "I think X is the root cause because Y."
• Proposed Fix: The smallest possible change to test this hypothesis.
• Defense-in-Depth Plan: "I will fix the source, AND I will add validation at layer Z to make this structurally impossible in the future."

Phase 3: Minimal Implementation

1. Create/Verify a Failing Test: Ensure you have a test that reliably fails because of this specific root cause.
2. Implement the Single Fix: Address the root cause identified in the RCA. ONE change at a time. No bundled refactoring.
3. Implement Defense-in-Depth: Add validations (Entry point, Business Logic, Environment Guards) so the bad data can never reach this deep into the stack again.

Phase 4: Verification & Circuit Breaker

Test your fix. If it passes, run the full suite to ensure no regressions.

THE 3-STRIKE CIRCUIT BREAKER: If your fix doesn't work:

1. STOP. Do not add more fixes on top.
2. If you have failed < 3 times: Return to Phase 1, gather new evidence, update the RCA doc.
3. If you have failed 3 times: Trigger the circuit breaker. STOP modifying code. Inform the user that the architecture or pattern might be fundamentally flawed and request a human review of the architecture.

Red Flags - STOP and Return to Phase 1

If you catch yourself thinking or saying:

• "Quick fix for now, investigate later"
• "Just try changing X and see if it works"
• "I'll use a 5-second timeout because the async task is slow"
• "One more fix attempt" (when already tried 2+) ALL of these mean: STOP. You are violating the Iron Law.

Required Workflow Integrations

• superpowers:test-driven-development - For creating the failing test case.
• superpowers:verification-before-completion - Verify fix worked before claiming success.

Supporting Techniques & Tools

When you need exact implementations for these steps, READ the following reference files located in this skill's directory:

• root-cause-tracing.md - How to trace bugs backward through the call stack.
• defense-in-depth.md - Examples of the 4 layers of validation to implement.
• condition-based-waiting.md & condition-based-waiting-example.ts - Code patterns for polling loops instead of arbitrary timeouts.
• find-polluter.sh - Executable bash script to bisect test state pollution.