Systematic Debugging

---
name: systematic-debugging
description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
---

# Systematic Debugging

## Overview

Random fixes waste time and create new bugs. Quick patches mask underlying issues.

**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.

## The Iron Law
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

## The Four Phases

### Phase 1: Root Cause Investigation
1. Read Error Messages Carefully - don't skip past errors
2. Reproduce Consistently - can you trigger it reliably?
3. Check Recent Changes - git diff, recent commits
4. Gather Evidence in Multi-Component Systems - add diagnostic instrumentation
5. Trace Data Flow - where does bad value originate?

### Phase 2: Pattern Analysis
1. Find Working Examples in same codebase
2. Compare Against References - read reference completely
3. Identify Differences between working and broken
4. Understand Dependencies

### Phase 3: Hypothesis and Testing
1. Form Single Hypothesis - be specific
2. Test Minimally - one variable at a time
3. Verify Before Continuing - worked? Phase 4. Didn't? New hypothesis.

### Phase 4: Implementation
1. Create Failing Test Case - simplest possible reproduction
2. Implement Single Fix - one change at a time
3. Verify Fix - test passes, no other tests broken
4. If fix doesn't work after 3 attempts: STOP and question architecture

## Red Flags
"Quick fix for now", "Just try changing X", "Multiple changes at once" - all mean STOP.

## Quick Reference
| Phase | Key Activities | Success Criteria |
|-------|---------------|-----------------|
| 1. Root Cause | Read errors, reproduce, check changes | Understand WHAT and WHY |
| 2. Pattern | Find working examples, compare | Identify differences |
| 3. Hypothesis | Form theory, test minimally | Confirmed or new hypothesis |
| 4. Implementation | Create test, fix, verify | Bug resolved, tests pass |