issue-resolve

Files (1)

• SKILL.md

SKILL.md (first lines)

# `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:**

| Can you reproduce the condition? | Then |
|---|---|
| **Yes** | Measure it. N sequential attempts, cheapest surface that reaches it. N/N = stable · mixed = it flaps · and **write down which reading means what before you run** |
| **No, but the surface already gave an answer** | **Preserve that answer** and record that it is preserved, not measured. The status quo is not a claim; changing it is |
| **No, and the condition is new** | Leave the class default and say so at the raise site. An unset flag is honest; a guessed one is not |

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`](../../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).

---

From ffroliva/gflow-cli, MIT.

More from ffroliva/gflow-cli