Raw view: Bug Report to Pull Request

No invisible, zero-width, or bidi-control characters detected.

# Bug Report to Pull Request

Turn the bug report below into a reviewed, mergeable pull request. The order matters: reproduce before diagnosing, diagnose before fixing, and prove the fix with a test that failed before it. A fix without a reproduction is a guess.

<bug_report>
{{BUG_REPORT}}
</bug_report>

Test command: `{{TEST_COMMAND}}`. Branch naming: `{{BRANCH_PREFIX}}/<short-slug>`. PR template: {{PR_TEMPLATE}} (use the repository's `.github/PULL_REQUEST_TEMPLATE.md` if this is empty and one exists).

## Phase 1: Understand and reproduce

1. Read the report and restate the bug in one sentence of the form "When X, the system does Y; it should do Z." If X, Y, or Z is missing from the report, list the question and make a reasonable assumption marked `[assumed]`.
2. Locate the code path. Search for the error message, the UI string, or the function named in the report. Read the relevant files fully before forming a theory; do not speculate about code you have not opened.
3. Reproduce. Prefer, in order: an existing test you can modify to show the bug; a new minimal test; a script; a manual sequence. Record the exact command and output that demonstrates the wrong behavior.
4. **Check:** you have a reproduction that fails deterministically. If you cannot reproduce after a reasonable effort, STOP and report what you tried, what you observed, and what information would help (environment, data, version).
5. **STOP POINT.** Present the one-sentence restatement, the reproduction, and your initial hypothesis. Wait for confirmation that this is the bug being reported before changing code.

**Artifact:** reproduction command and output, saved in the branch notes or PR draft.

## Phase 2: Diagnose

6. Create the branch: `{{BRANCH_PREFIX}}/<short-slug>`.
7. Form 1-3 hypotheses for the root cause, each tied to specific lines. Design the cheapest check that distinguishes them (a log line, a breakpoint, a unit test on the suspected function).
8. Run the check. Keep going until exactly one hypothesis survives and you can state the root cause as a fact about program state, not a symptom.
9. **Check:** the root cause explains every detail in the report, including any "only happens when" conditions. If it explains only some, you have a contributing factor, not the cause; keep going.

## Phase 3: Regression test

10. Write a test that encodes the correct behavior and fails on the current code because of the root cause. Name it after the behavior, not the bug number. Match the surrounding tests' style.
11. Run `{{TEST_COMMAND}}`. **Check:** the new test fails with a message that points at the root cause. Record it.

## Phase 4: Fix

12. Make the smallest change that fixes the root cause. Do not refactor surrounding code, do not fix adjacent bugs you noticed (note them for a separate issue), do not add defensive checks for cases that cannot happen.
13. Run `{{TEST_COMMAND}}`. **Check:** the regression test passes; nothing else changed state. Run the full suite, lint, and type checks.
14. Re-run the original reproduction from step 3. **Check:** it now shows correct behavior.
15. **STOP POINT.** If the fix requires changing a public interface, a database schema, or behavior other callers may depend on, stop and present the options before proceeding.

## Phase 5: Pull request

16. Review the full diff as a reviewer would: every hunk must be either the test or the fix. Remove anything else.
17. Write the PR description using {{PR_TEMPLATE}} or this structure:
    - **Problem:** the one-sentence restatement.
    - **Root cause:** 2-4 sentences, referencing the file and function.
    - **Fix:** what changed and why this is the minimal change.
    - **Verification:** the regression test name, the reproduction command, the before/after output.
    - **Risk:** who else calls this code; what to watch after deploy.
    - **Out of scope:** adjacent issues noticed and not fixed, as follow-up candidates.
18. Link the original issue. Request review from the code owners of the touched files.

**Final artifact:** the open PR with the description above, plus a list of follow-up issues to file.

## Rules throughout

- Do not change the test to match the buggy behavior.
- Do not suppress the error (catch-and-ignore, widen a type, add a null check) unless the suppression is the correct behavior and you can say why.
- If at any point the fix is growing beyond roughly 50 changed lines, pause and ask whether a larger change is wanted.