debug

# Systematic Debugging

## Overview

Random fixes waste time and create new bugs. Quick patches mask underlying issues.
Follow the four phases to find root cause before attempting any fix.

**Core principle:** NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.

**Announce at start:** "I'm using the debug skill to investigate this issue."

## The Iron Law

```
If you haven't completed Phase 1, you cannot propose fixes.
```

## When to Use

Use for ANY technical issue:
- Test failures
- Runtime errors
- Unexpected behavior
- Performance problems
- Build failures

**Use ESPECIALLY when:**
- Under time pressure (emergencies make guessing tempting)
- "Just one quick fix" seems obvious
- Previous fix didn't work
- You've tried multiple fixes already

## The Four Phases

### Phase 1: Root Cause Investigation

**BEFORE attempting ANY fix:**

1. **Read Error Messages Carefully**
   - Don't skip past errors or warnings
   - Read stack traces completely
   - Note line numbers, file paths, error codes

2. **Reproduce Consistently**
   - Can you trigger it reliably?
   - What are the exact steps?
   - If not reproducible - gather more data, don't guess

3. **Check Recent Changes**
   ```bash
   git diff HEAD~5           # Recent changes
   git log --oneline -10     # Recent commits
   ```

4. **Check Existing Knowledge**
   ```bash
   kodo query "similar bug"       # Was this fixed before?
   kodo query "error handling"    # Known patterns
   ```

5. **Trace Data Flow**
   - Where does the bad value originate?
   - Trace backward through call stack
   - Find the SOURCE, not the symptom

### Phase 2: Pattern Analysis

1. **Find Working Examples**
   - Locate similar working code in codebase
   - What works that's similar to what's broken?

2. **Identify Differences**
   - What's different between working and broken?
   - List every difference, however small

### Phase 3: Hypothesis and Testing

1. **Form Single Hypothesis**
   - State clearly: "I think X is the root cause because Y