systematic-debugging

# Systematic Debugging

Find the root cause before attempting fixes. Symptom fixes are failure.

## Purpose

Debugging without methodology wastes time and creates new bugs. Random fixes
address symptoms, not causes. This skill enforces systematic investigation
to find root causes before any fix is attempted.

## The Iron Law

**ALWAYS find root cause before attempting fixes.**

Quick patches mask underlying issues. If you're trying fixes without
understanding why they might work, you're guessing - stop and investigate.

## The Four Phases

Complete each phase in order. Do not skip to implementation.

### Phase 1: Root Cause Investigation

**Understand what's happening before theorizing why.**

1. **Read the error carefully**
   - Full error message, not just the first line
   - Stack trace - where did it originate?
   - Error codes or types

2. **Reproduce consistently**
   - Can you trigger the failure reliably?
   - What are the exact steps?
   - Does it fail the same way every time?

3. **Review recent changes**
   - What changed since it last worked?
   - Check git log for recent commits
   - Any new dependencies or configuration?

4. **Gather diagnostic evidence**
   - Add logging at key points
   - Check system state (memory, disk, network)
   - Inspect input data

5. **Trace backwards**
   - Start from the error
   - Work backwards through the call stack
   - Find where correct behavior diverges

### Phase 2: Pattern Analysis

**Compare against working code.**

1. **Find similar working code**
   - How does a working version do this?
   - What's different about this case?

2. **Compare against references**
   - Documentation examples
   - Library/framework conventions
   - Previous implementations

3. **Identify the difference**
   - What's unique about the failing case?
   - What assumption is being violated?

4. **Understand dependencies**
   - What does this code depend on?
   - Could a dependency have changed?
   - Are versions correct?

### Phase 3: Hypo