/resolve-author-fix

name: resolve-author-fix
description: Find the root cause, implement a focused fix, and prove behavior with targeted tests and recordings.

Step 2B — Author the fix

No candidate PR exists, so you fix it yourself. Steps 2B.1–2B.5 below are the full author flow; then open a PR in Step 3.

2B.1 — Confirm the shared repro audit

Complete the shared repro audit before changing product code. Reuse its recorded behavioral baseline rather than trusting the recovered verdict or rerunning an unchanged audit. If the test, base, or relevant environment changes, repeat the audit. Ticket-only mode instead establishes its targeted fail→pass proof in 2B.4. The failure-quality checks below elaborate the shared requirement; they do not replace patch inspection or excuse the review path from the same audit.

It **must fail because the buggy behavior is observed** — a wrong value, an error toast, a traceback, a bad HTTP response, a missing/incorrect UI affordance.

It **must not** fail merely because it references something that does not exist yet — an `AttributeError`/`ImportError` on a symbol the fix would add, an element-not-found for UI the fix would introduce, a 404 on a route the fix would register. That is an **existence-check**, not a reproduction: it would go green the moment the symbol exists, regardless of whether the behavior is correct. If the test fails that way:

• **Rewrite it into a behavioral assertion** that exercises the real journey and

asserts the correct *behavior/value*, and confirm the rewrite fails for the right reason before proceeding.

• **Flag it loudly** in your handoff (`test_audit`) so a reviewer knows the

original repro test was an existence-check and you corrected it.

**If the test PASSES on the unfixed tree, it may be stale or unreliable; do not assume `main` has fixed the bug.** A recovered verdict is a statement about main AT REPRO TIME, not now. Verify the way repro-agent would: re-drive enough of the journey to confirm the behavior is genuinely correct on the current tree, and hunt for the fixing commit (`git log` on the code the evidence points at). When it is really fixed, do not manufacture work: stop with outcome `nothing_to_fix`, name the fixing commit in `root_cause`, and recommend closing the ticket in your prose summary. If the test passes but the journey still misbehaves, the test was too loose — treat it like the existence-check case above: rewrite it until it fails on the real, still-live behavior, and flag the rewrite in `test_audit`.

For a **compound** bug, do this for **every facet whose verdict is `reproduced`**. Facets already `already_fixed` need no transition (note them skipped). Record, per live facet, the **exact fail reason** — the "from" half of your fail→pass proof.

2B.2 — Root-cause

Apply `resolve-investigate`: match the reported path and configuration, check competing explanations, and find the historical rationale. State the supported cause before editing. If policy must change, distinguish that proposal from repairing an implementation defect and retain unresolved choices for PR review.

2B.3 — Implement the fix

Fix the root cause, not the symptom. Change the code the bug lives in, matching surrounding conventions, as small as the root cause allows. Do not touch the test to make it pass; the *code* must change to satisfy it.

2B.4 — Select permanent regression coverage

Read `tests/README.md` and `tests/_helpers/README.md` in the product checkout before writing setup (or nearby fixtures when that repository has no catalog). Follow its API examples and the selection policy below. In `test_audit`, name the nearest test/helper considered, explain any new setup, and report permanent test/support additions and deletions including helper changes.

Choose which tests belong in the final PR. Search existing tests by behavior and fixture, and read the nearest scenarios. If one already drives the relevant setup and state transition, fold the missing assertions into it; parameterize configuration variants when useful. Apply this to recovered Repro tests too: archive the original, then consolidate its regression assertions into the existing scenario. Keep a separate test when a distinct ordering or boundary would make that extension misleading. Keep investigation history in evidence and test comments short. Reuse unchanged coverage when sufficient; there is no requirement for a new test file or both a new e2e and a smaller test.

When existing coverage is insufficient, start with an edit to the nearest compatible scenario: preserve its existing assertions and add the regression input, seed records, or missing assertion. Leave sufficient coverage unchanged. Needing richer data does not make its journey incompatible. Keep a separate scenario only for a concrete ordering, lifecycle, or isolation conflict; name that conflict and the nearest existing test in `test_audit`. Before final verification, compare the setups and consolidate any compatible duplication. Moving a reproduction into an existing file is not consolidation.

Each reported facet needs reliable coverage, not coverage at every layer. Keep the input and edge-case matrix at the lowest reliable layer. At a higher layer, use a representative regression input for each distinct boundary the lower tests cannot expose; do not replay the whole matrix there. A new helper does not automatically need direct unit tests when its real callers already exercise its contract. Retain a helper test only for behavior those caller checks miss. For every added layer, briefly identify the regression that would escape the other selected checks if that layer were omitted.

Retain an e2e when it protects a distinct production boundary that lower-level coverage would miss, and explain that boundary briefly in `test_audit`. Do not mock away the failure, skip configurations, or supply already-correct objects in place of testing serialization, startup, process, or browser wiring. For do