bugfix

# Bugfix

## Purpose

Structured debugging methodology for fixing bugs. Ensures bugs are properly understood before fixing, captured in tests to prevent regression, and fixed with minimal changes.

## Quick Reference

- **Phases**: Reproduce → Plan → Failing Test → Fix → Verify
- **Key Rule**: Never fix without a failing test
- **Output**: Minimal fix + test that prevents regression

## Bug Fix Phases

```
┌─────────────────────────────────────────────────────────────────────────────────┐
│                              BUG FIX WORKFLOW                                    │
├─────────────────────────────────────────────────────────────────────────────────┤
│  1. REPRODUCE  →  2. PLAN  →  3. FAILING TEST  →  4. FIX  →  5. VERIFY          │
└─────────────────────────────────────────────────────────────────────────────────┘
```

## Phase B1: Reproduce the Bug

**Goal:** Confirm the bug exists and understand how to trigger it.

**Procedure:**
1. Read the ticket description and any error logs/screenshots
2. Identify the reproduction steps from the ticket
3. Execute reproduction steps in local environment
4. Document the observed behavior vs expected behavior
5. If cannot reproduce: ask user for more context, check environment differences

**Output:** Bug reproduction confirmed with clear steps

```markdown
## Bug Reproduction
- **Steps to reproduce:**
  1. ...
  2. ...
- **Expected:** ...
- **Actual:** ...
- **Environment:** <runtime version>, <os/platform>
```

**Key Rule:** Cannot proceed without reproduction. If you can't trigger the bug, you can't verify the fix.

## Phase B2: Plan (Root Cause + Fix)

**Goal:** Understand WHY the bug occurs and design the fix approach.

**Procedure:**
1. Trace the code path from reproduction steps
2. Read relevant source files
3. Form hypothesis about the cause
4. **If root cause is unclear:**
   - Add debug logging (logger.debug, NOT console.log)
   - Run with debug logs and analyze output
   - **Do NOT change implementation code yet*