bug-fix

Bug Fix

Use a tight reproduce -> diagnose -> fix -> verify loop. Prefer the smallest command that proves the failure and the smallest change that fixes it.

Workflow

1. Capture the failure

   • Read the user report, logs, failing test name, branch state, and recent diff.
   • If no command is known, inspect project docs, package manifests, CI config, or existing test scripts.
   • State the concrete symptom before changing code.

2. Reproduce narrowly

   • Run the smallest relevant test or command first.
   • For runtime bugs, re-run the original crash, CLI command, page action, log-producing step, or CI step when possible.
   • If the full suite is the only known command, run it once, then narrow from the output.
   • Preserve the important error lines, assertion, stack trace, exit code, and failing file.
   • If the bug has no failing test and a focused regression test or reproduction script is practical, create it before changing production code.

3. Localize the cause

   • Compare failing behavior against nearby tests, recent changes, and existing patterns.
   • Inspect production code and tests together; do not assume the test is wrong.
   • Form one working hypothesis at a time and verify it with code or command output.

4. Fix minimally

   • Change only files needed for the failure.
   • Prefer existing helpers, local conventions, and simple control flow.
   • Do not rewrite unrelated code while debugging.

5. Verify the fix

   • Re-run the original failure path first: failing test, crash command, page action, CI step, or log-producing command.
   • Re-run the narrow failing command if it differs from the original path.
   • Run the adjacent or broader test command that could catch regressions.
   • If no automated regression test was practical, run a smoke check and record the remaining risk.

6. Report evidence

   • Summarize the root cause, changed files, and verification commands with pass/fail results.
   • If a command cannot run, say exactly why and what risk remains.