Debug

Debug a reported issue using a structured reproduction-then-fix approach.

Phase 1: Reproduction & Root Cause Analysis

Investigate — Analyze the bug report for key symptoms and error messages
Trace — Search the codebase for error occurrence patterns, trace from symptom to source
Root cause — Identify the root cause through data flow analysis and edge case checking
Reproduce — Reproduce the exact error with the smallest useful check (a command, dry run, manual flow, or automated test)
Document — Clearly document the root cause and reproduction steps

Plan — Analyze the optimal fix approach based on root cause, check for similar fixes in the codebase
Implement — Make the minimal, targeted fix that addresses the root cause
Verify — Repeat the reproduction to confirm the fix and run relevant existing checks. Follow verify-and-ship for proportionate scope; add a regression test only when the concrete failure warrants durable coverage

Minimal changes — Fix the bug, nothing more
Targeted — Only touch affected code paths
Verified — Confirm the reproduction succeeds after the fix and preserve relevant existing safeguards; a new test file is not mandatory
No unrelated improvements — Stay focused on the specific bug