Issue Resolve

issue-resolve — drive an assessed issue to a draft PR

Takes a verdict from issue-assessment and produces a reviewable fix. The terminal state is a draft PR a human promotes — never an autonomous merge.

Core principle: the agent's job is to get the problem review-ready, not to declare victory. A fix is "verified" only after it runs green on the affected surface; when that surface can't be reached here (headed Flow browser, macOS-only, credits), say so in the PR and stop. (Memory: done-means-e2e-verified, pr-must-verify-on-affected-surface.)

The Bug Lane — canonical here, cited everywhere

This is the chain a bug travels in gflow-cli. It is written out once, in this file. AGENTS.md, skills/spike, skills/scenario and docs/E2E_TESTING.md all point here — none of them restate it, because a duplicated checklist drifts.

0  SPIKE       measure the live surface            ── only when a claim about Flow is in play
1  DEBUG       systematic-debugging → ROOT CAUSE   ── the symptom is never the finding
2  SCENARIO    BDD Gherkin written at the ROOT     ── the reproduction, in Given/When/Then
3  TDD         that Gherkin RED before any fix     ── red for the right reason
4  FIX         minimal change, at the root         ── grep every caller before editing one
5  FORMALIZE   UI/Flow surface ⇒ it is an E2E test ── a browser-free proxy does not discharge it

The surface gate — steps 0–2 are conditional, 3–5 never are

Run 0 SPIKE when the bug's explanation involves what Flow does — a selector, a wire response, a host behaviour, any claim of absence. Skip it when the cause is already proven or lives entirely in our own code.

Run 1 DEBUG and 2 SCENARIO whenever the bug touches a Flow surface, a transport, auth, selectors, or the cause is not yet proven. Skip both for a fix whose cause is self-evident and whose blast radius is one line — a typo, an exit-code string, a doc correction. A skip is a claim; say it out loud ("cause proven at <file>:<line>, skipping the debug step") so the skip is reviewable.

Steps 3–5 have no gate — but read step 3 correctly when step 2 was skipped. There is no bug small enough to fix without a test that failed first, and no Flow-surface change that a unit test discharges. What step 3 requires is the reproduction, red first; Gherkin is its form only when step 2 produced Gherkin. Skip step 2 and step 3 still owes you a failing test — an ordinary test_* that reproduces the bug — it just is not a scenario. The gate is red before green, never Gherkin before green.

A flag is a claim — decide it with evidence or don't change it

retryable, an exit code, a capability-table entry, a skip_if_* predicate: these are read by code that acts on them. retryable=True is not a hint, it is an instruction to try again. So metadata obeys the same rule as prose — a claim you have not run is a guess with formatting. The trap is that a flag changes for free when you re-route a raise to a different class, so a refactor smuggles in an assertion nobody reviewed.

How to decide, in order:

Never let a class default speak for a raise site it was not written for. When one class covers shapes with genuinely different semantics, give the raise site an override rather than picking one answer for both — FlowAppError.retryable exists for exactly this, and lives on that class alone until a second one needs it.

Written from a near-miss in the same session that wrote this file. Routing #756's /about landing to FlowAppError (exit 31) would have flipped it from non-retryable to retryable purely as a side effect of the exit-code change, and the first draft shipped that with a confident remediation string saying a retry was "unlikely to help" — also unmeasured. The maintainer caught it: "I need evidence and test. otherwise everything will be a guess." The measurement came back inconclusive (the redirect had stopped reproducing), which is why the rule's middle row exists: inconclusive is a real result, and it means preserve, not pick.

Step 5 is the one that gets rationalised away

IF THE SCENARIO CAN ONLY HAPPEN IN A BROWSER,
THE TEST THAT PROVES IT IS AN E2E TEST.

Not a unit test with a mocked page. Not "the CLI path is covered and it shares the service." Those assert that our code does what we think; the bug was that Flow did something else. Write tests/e2e/test_<slug>_bdd.py, binding the Gherkin from step 2 — see docs/E2E_TESTING.md § BDD-bound e2e for the tag/marker mechanics.

The only exit is a named external blocker (AGENTS.md Iron Law): an account you do not control, hardware you do not have, an exhausted quota. Write it down, use Refs #N not Closes #N, and leave the issue open. "I could not reach it here" is a blocker only after you have said what stopped you.

Written from the contradiction it removes. Until 2026-09-10 step 3 of this file read "the test is the closest browser-free proxy" while AGENTS.md's Iron Law read "if no e2e test covers the change, write one — that is part of the change," and listed "it's covered by unit tests" among the excuses that are not blockers. Two files, disjoint, no merge conflict, no gate that could see it — memory prose-conflicts-hide-in-disjoint-files. An agent following this skill could ship a mocked proxy and be, by the letter, compliant.

Preconditions (all required before any code change)

1. An issue-assessment verdict of CONFIRMED-BUG or LIKELY-BUG.
2. Scope is single-surface / localized (not a cross-cutting redesign).
3. The fix is verifiable in this environment, OR the gap is a named external blocker carried into the PR. "Browser-free" is not itself a blocker — this host has a warm profile and runs the e2e_auth tier at zero credits nightly. Name what actually stops the run (an account you do not control, a Mac, an exhausted quota) or run it.

If any fails → do not resolve; return to issue-assessment (reply-only).

Autonomy envelope (the action contract)

Allowed autonomously:

• ✅ Post one issue comment (status / reply to reporter).
• ✅ Open a draft PR (push a bugfix/-prefixed branch off develop).
• ✅ Run browser-free / credit-free verification (unit, lint, type, recording-verif, Gemini tool-path).
• ✅ Run the council review (/gflow:pr-council-review / /gflow:branch-review), /gflow:check, /gflow:sonar, /gflow:doc-review — without asking. These are mandated steps, not offers. A general "don't spawn subagents unless the user requested it" rule does not gate them: the user requested them by invoking this workflow. Stopping to ask makes the maintainer re-authorize the same step every issue, and it stalls the pipeline at exactly the point review is worth most.

Never (these require a human, regardless of pressure):

• ❌ Spend Veo credits (no live video generation to "verify").
• ❌ Mark a PR ready for review or merge it.
• ❌ Push to main or develop.
• ❌ State a fix is "verified" / "fixed" when it was not run on the affected surface.

Red flags — if you catch yourself reasoning toward any of these, STOP: "just spend one credit to exercise the path", "it's obviously correct, merge it", "mark it ready to save the human time", "say it's verified so we can close it". Urgency does not make an unverified fix verified.