issue-assessment — triage a gflow-cli issue honestly

Read-only conductor. Verify the reporter's claim against the code, tests, docs, KNOWN_ISSUES.md, and auto-memory; classify it; judge whether it can be verified end-to-end in the current environment; and draft a reply. The output is a standard artifact a human or the issue-resolve skill can act on.

Core principle: never assert more than the evidence supports. A claim is CONFIRMED only with line-level code evidence or a reproduction; a fix is "verified" only after running it on the affected surface. Honest "can't verify here" beats a false green check — a bounced fix costs more trust than an accurate "not yet."

---

When to invoke

• A new or updated GitHub issue needs a verdict before anyone spends effort.
• An autonomous run (hermes-ops) reacts to an issue labelled for triage.
• You're about to "just fix" a reported bug — assess first; the scope decision (reply-only vs hand to issue-resolve) depends on this.

Skip for: issues that are obviously feature requests routed elsewhere, or already-triaged issues entering implementation.

---

Invocation

/gflow:issue-assessment <issue number or URL>

This repo's skills/*/SKILL.md are plain Markdown — invoke by reading the file (via the .claude/commands/gflow/* wrapper), never Skill(skill=...).

---

Protocol

1. Ingest

gh issue view <N> --json title,body,comments,labels,author,state. Extract: the claimed symptom, environment (OS, version, install method), exact repro steps, and any logs/error classes the reporter pasted.

2. Verify (read-only)

Dispatch a search/Explore agent (keep your own context clean) to corroborate or refute the claim against the real tree. Always check, in order:

• the source path(s) the symptom implicates — cite file_path:line_number;
• KNOWN_ISSUES.md (is this Open / Mitigated / Resolved already?);
• open issues/PRs (gh pr list, gh issue list) for duplicates or in-flight fixes;
• auto-memory for prior context on the surface. Disprove parts of the reporter's framing where the code says otherwise (e.g. browser_engine: playwright is the engine axis, not the channel) — a precise correction is more useful than agreement.

Name the affected SURFACES, not just the affected code. A reporter hits one surface; the defect usually spans both. gflow ships most capabilities twice — CLI command and MCP tool — so state explicitly whether the issue reproduces on the CLI, on the MCP tool, or on both, and whether a fix in one automatically fixes the other (it does when both route through the same transport; it does not when the MCP path carries its own params through worker/codec.py). Getting this wrong scopes the whole downstream fix wrong: a "CLI bug" that is really a shared-transport bug leaves MCP users broken after the issue is closed.

3. Classify — exactly one verdict

Verdict	Meaning
CONFIRMED-BUG	Reproduced, or root-caused in code with line-level evidence.
LIKELY-BUG / NEEDS-E2E	Strong code hypothesis, but unverifiable in this environment (e.g. macOS-only or headed-browser bug on a headless/Windows host).
NEEDS-INFO	A specific discriminating diagnostic is required before deciding.
DUPLICATE / KNOWN-ISSUE	Matches an open issue/PR or a KNOWN_ISSUES.md entry.
WORKING-AS-INTENDED / INVALID	Usage error or expected behavior.
WONTFIX / OUT-OF-SCOPE	Real but deliberately not addressed.

4. e2e-gate — what would verification actually require?

Classify the verification cost before claiming anything is fixed:

• Browser-free (pure-Python logic, Gemini tool-path, unit/lint/type, recording-verif) → verifiable anywhere, including the headless VPS. Run it.
• Headed-Flow-browser required (generation, selector, auth, reCAPTCHA) → not verifiable on a headless or wrong-OS host. Verdict tilts to LIKELY-BUG / NEEDS-E2E; never claim success; the final check is a human on the affected surface. (See memory: done-means-e2e-verified, pr-must-verify-on-affected-surface.)

5. Report (the artifact)

Produce the reply below. Post it only if the autonomy gate allows (autonomous runs may comment; otherwise surface for a human to send).

**Assessment of #<N>: <verdict>** (confidence <N>/10)

Restated claim: <one line>.

Findings:
- <evidence as file:line> …
- <corrections to the reporter's framing, if any> …

Root cause / hypothesis: <what and why, or "unconfirmed because …">.

What we need next:
- <the single discriminating diagnostic — for NEEDS-INFO/NEEDS-E2E>, or
- <draft PR link — if issue-resolve ran>, or
- <why this is a dup/invalid/wontfix>.

6. Hand-off decision (graded, not a hard stop)

• Verdict ∈ {CONFIRMED-BUG, LIKELY-BUG} and scope is single-surface/localized and a fix is verifiable in this environment → chain to issue-resolve (Phase 9) or predict (Phase 2).
• Otherwise → reply only; the next step is a human or more info.

Pipeline Continuation (Next Step Handoff)

Upon completing an Issue Assessment:

1. Confirmed Bug / Feature Request: Proactively announce: "Issue assessed. Next step: Phase 2 Pre-Implementation (/gflow:predict <proposal>) or Phase 9 Issue Resolve (/gflow:issue-resolve <N>)."
2. Needs Info / Unconfirmed: Request the specific diagnostic and await information before moving to Phase 2.

---

Skill routing (do not hallucinate skill names)

Re-derive this from ls skills/ + ls .claude/commands/gflow/ before relying on it — names drift. Current map:

Need	Use	How
The issue claims a surface is broken/missing/impossible	/gflow:spike	read skills/spike/SKILL.md — do this before classifying
High-stakes change (auth/transport/selector/schema)	/gflow:predict	read skills/predict/SKILL.md
Edge cases + BDD skeleton	/gflow:scenario	read skills/scenario/SKILL.md
Touching auth/reCAPTCHA	/gflow:known-issues	.claude/commands/gflow/known-issues.md
Drive the fix	issue-resolve	read skills/issue-resolve/SKILL.md
Worktree / TDD	superpowers	Skill() tool (these are invocable)

Before you classify an absence

A verdict of INVALID / WONTFIX / "not supported on this host" is a claim about the live product, and this skill is read-only — it cannot produce one from the code alone. If the issue asserts that something does not work, and the answer turns on what Flow actually renders or calls, load skills/spike/SKILL.md and get evidence first.

The failure this prevents: a 20 s selector timeout was read as "the character editor is a labs-only surface, it renders no prompt textbox ever", and that unmeasured negative reached a code comment, a CHANGELOG entry, a release ledger and a test class name before anyone looked at the DOM. The feature had worked the whole time. Closing a reporter's issue on that basis tells a user their working feature is impossible.

Cheap tells that you are about to do it:

• the evidence for the absence is a timeout, an exception, or an exit code
• the claim is about a host, cohort or account class you cannot check from here
• you are about to write "cannot", "never", "not supported" in a reporter-facing reply

Spikes are free for DOM and network reads. Thirty minutes of measurement beats a confident wrong classification that ships.

---

Output format

A single Markdown block: the verdict line, findings with citations, root-cause hypothesis, and the "what we need next" step. No code changes, no posting unless the autonomy gate permits.

---

Provenance

Designed 2026-06-29 (docs/superpowers/specs/2026-06-29-issue-assessment-workflow-design.md). Validated against issue #222 (a LIKELY-BUG / NEEDS-E2E case: macOS + headed browser, unverifiable on Windows/headless). Authored recipe-shaped after three baseline runs showed capable agents already comply with the project's discipline rules — the skill standardizes the procedure and artifact, it does not enforce discipline the agent lacks.