systematic-debugging

# Systematic Debugging Process

## Overview

This skill provides a disciplined, phase-based approach to debugging that ensures root cause identification rather than symptom treatment. The methodology emphasizes systematic investigation, hypothesis testing, and minimal incremental fixes.

## When to Use This Skill

Use this skill whenever:
- Debugging a technical issue or error
- Investigating unexpected behavior
- Troubleshooting test failures
- Resolving performance problems
- Analyzing system failures

## Core Principle

**ALWAYS find the root cause of any issue. NEVER fix a symptom or add a workaround instead of finding the root cause, even if it appears faster or more expedient.**

## Four-Phase Debugging Framework

### Phase 1: Root Cause Investigation

**Perform BEFORE attempting any fixes.** This phase focuses on understanding the problem completely.

#### Read Error Messages Carefully
- Don't skip past errors or warnings
- Error messages often contain the exact solution
- Note stack traces, line numbers, and context
- Look for patterns in multiple error occurrences

#### Reproduce Consistently
- Ensure the issue can be reliably reproduced
- Identify the minimal steps to trigger the problem
- Note any conditions that affect reproducibility
- Document the exact environment and context

#### Check Recent Changes
- Review what changed that could have caused this
- Use `git diff` to examine recent modifications
- Check recent commits and their impact
- Consider dependency updates or configuration changes

### Phase 2: Pattern Analysis

This phase involves comparing working and non-working states to identify differences.

#### Find Working Examples
- Locate similar working code in the same codebase
- Identify what makes the working example successful
- Note the context and dependencies of working code

#### Compare Against References
- If implementing a pattern, read the reference implementation completely
- Don't skim documentation—read it thoroughly
- Understand