debug-cycle

# Debug Cycle - PDCA Framework

## Overview

A systematic, platform-agnostic approach to debugging using the PDCA (Plan-Do-Check-Act) cycle. This methodology provides a structured workflow for forming hypotheses, adding instrumentation, analyzing behavior, and iterating until root cause identification.

## When to Use

- Debugging issues that require observation of runtime behavior
- Investigating problems that cannot be determined through static analysis alone
- Verifying that a fix actually resolves the issue
- Understanding data flow through complex systems
- Troubleshooting intermittent or timing-related bugs
- Any scenario where "guess and check" has failed

## The PDCA Cycle

### Phase 1: Plan (Hypothesis Formation)

**Objective**: Form a testable hypothesis about the root cause.

**Steps**:
1. **Document the symptom** - Describe the observed behavior precisely
2. **Form a hypothesis** - What specific condition might cause this?
3. **Identify data points** - What values/states would confirm or refute the hypothesis?
4. **Determine instrumentation points** - Where should debug output be added?

**Hypothesis Template**:
```
Symptom: [Precisely what is happening]
Expected: [What should happen instead]
Hypothesis: [Specific cause I believe is responsible]
Data needed: [Values/states to capture]
Instrumentation points: [Files, methods, lines to add logging]
```

**Good vs Bad Hypotheses**:

| Bad (Vague) | Good (Specific) |
|-------------|-----------------|
| "Something is wrong with the data" | "The user ID is null when passed to fetchProfile()" |
| "The UI isn't updating" | "setState is not being called after the API response" |
| "It's slow" | "The database query is executing N+1 times in the loop" |

### Phase 2: Do (Instrument & Build)

**Objective**: Add targeted instrumentation to capture the data needed.

**Steps**:
1. **Add debug logs** at identified points
2. **Include contextual information**:
   - Variable values at decision points
   - Method entry/exi