Debugging Workflow

PROSE constraints: Reduced Scope (narrow the problem systematically) + Progressive Disclosure (gather context incrementally).

Phase 1: Understand the Problem

1. •Parse $ARGUMENTS for error messages, stack traces, or symptom descriptions
2. •Search the codebase for relevant code paths
3. •Read related test files to understand expected behavior

Phase 2: Reproduce

1. •Identify a minimal reproduction path
2. •Run relevant tests to confirm the failure: npm test -- [relevant-test]
3. •If no test exists, create one that demonstrates the bug

Phase 3: Isolate

1. •Trace the execution path from symptom to root cause
2. •Check recent changes: git log --oneline -20
3. •Narrow scope — identify the single function or condition causing the issue
4. •State the root cause clearly before proceeding

Validation Gate

STOP: Present the root cause analysis and proposed fix. Wait for confirmation.

Phase 4: Fix

1. •Make the minimal change that fixes the root cause
2. •Don't refactor surrounding code — fix the bug only
3. •Update or add a test that would have caught this bug

Phase 5: Verify

1. •Run the failing test to confirm it passes: npm test -- [test-file]
2. •Run the full test suite to check for regressions: npm test
3. •Run the linter: npm run lint

Output Summary

## Bug Fix: [title]

### Root Cause
[What was wrong and why]

### Fix
[What was changed]

### Files Modified
- [file] — [change description]

### Verification
- [test] — passes
- Full suite — no regressions