systematic-debugging

# Systematic Debugging

A systematic approach to debugging that ensures you understand the root cause before attempting fixes. This reduces thrashing, prevents new bugs, and saves time.

## When to Use

**Use this skill when you encounter:**
- Error messages or stack traces in conversation
- Test failures being discussed
- "Not working", "bug", "broken", or "unexpected behavior" mentioned
- Questions like "why is this happening?" or "help me debug"
- User reports something failing after changes
- Performance problems or build failures

**This skill provides structure to prevent:**
- Random fixes without understanding root cause
- Multiple simultaneous changes that can't be isolated
- Skipping tests and manual verification
- Thrashing when 3+ fixes have failed

## Examples

### Test Failure
```
"This test is failing: AssertionError: Expected 200 but got 500"
"help me debug this failing test suite"
"Why is the user auth test suddenly broken?"
```

### Runtime Error
```
"I'm getting TypeError: Cannot read property 'x' of undefined"
"This worked yesterday but now throws an error"
"Something's broken after my refactor"
```

### Build/CI Issues
```
"The CI pipeline is failing randomly"
"Build works locally but fails in production"
"Getting intermittent failures in our deployment"
```

## Core Workflow

### 1. Capture Error Context

Gather information about the problem:
- Read error messages and stack traces completely
- Note line numbers, file paths, error codes
- Check logs for additional context
- Understand what the system is telling you

### 2. Identify Reproduction Steps

Can you trigger the issue reliably?
- What are the exact steps to reproduce?
- Does it happen every time or intermittently?
- What conditions trigger it?
- If not reproducible: gather more data, don't guess

### 3. Isolate Failure Location

Where exactly does the problem occur?
- Trace the data flow to find where it breaks
- Check recent changes that could cause this
- Use diagnostic logging for mul