Systematic Debugging

Core principle: Find root cause before attempting fixes. Symptom fixes are failure.

The Four Phases

Complete each phase before proceeding to the next.

Debugging Progress:

• Phase 1: Root Cause Investigation
• Phase 2: Pattern Analysis
• Phase 3: Hypothesis Testing
• Phase 4: Implementation

Phase 1: Root Cause Investigation

Before attempting ANY fix:

• Read error messages carefully - Stack traces often contain the solution

• Reproduce consistently - If not reproducible, gather more data

• Check recent changes - Git diff, new dependencies, config changes

• Trace data flow backward - Find where invalid data originates

For multi-component systems: Add diagnostic logging at each component boundary before proposing fixes. See references/debugging-techniques.md for instrumentation patterns.

For log-heavy investigations: Use Skill(ce:reading-logs) for efficient analysis.

Phase 2: Pattern Analysis

• Find working examples of similar code in the codebase

• Compare working vs broken - list every difference

• Read reference implementations completely, not just skimming

Phase 3: Hypothesis Testing

• Form single hypothesis: "X is the root cause because Y"

• Make the SMALLEST possible change to test it

• Verify before continuing - if wrong, form NEW hypothesis

Phase 4: Implementation

• Create failing test case first

• Implement single fix at root cause

• Apply defense-in-depth - Validate at multiple layers

• Verify fix and run tests

If 3+ fixes have failed: Stop fixing symptoms. Question the architecture.

Red Flags

Stop and return to Phase 1 if you catch yourself:

• Proposing fixes without completing investigation

• "Just try changing X and see if it works"

• Adding multiple changes at once

• "It's probably X, let me fix that" (without evidence)

• Each fix reveals new problems in different places

Tactical Techniques

For specific debugging methods, see references/debugging-techniques.md:

• Binary search / git bisect

• Minimal reproduction

• Strategic logging

• Runtime assertions

• Differential analysis

• Multi-component instrumentation

• Backward tracing

Reporting Format

Root Cause

[1-3 sentences explaining underlying issue] Located in: file.ts:123

What Was Wrong

[Specific problem - mutation, race condition, missing validation, etc.]

The Fix

[Changes made and why they address root cause]

Verification

• Bug reproduced and confirmed fixed
• Existing tests pass
• Added regression test