--- name: Issue Assessment slug: issue-assessment category: Quality description: Issue Assessment reviews a gflow-cli issue against code, tests, and docs to decide whether the claim is confirmed, needs more info, or is already known. It also checks whether the issue can be verified end to end and drafts a reporter-facing reply. github: "https://github.com/ffroliva/gflow-cli/tree/develop/skills/issue-assessment" language: Python stars: 173 forks: 47 install: "npx degit https://github.com/ffroliva/gflow-cli/tree/develop/skills/issue-assessment ~/.claude/skills/issue-assessment" installs_to: ~/.claude/skills/issue-assessment source_path: skills/issue-assessment/SKILL.md collection_size: 18 category_size: 1897 collection_url: "https://dirskills.com/collections/ffroliva/gflow-cli" added: 2026-09-08T05:33:25.935Z last_synced: 2026-09-08T05:33:25.935Z canonical_url: "https://dirskills.com/skills/issue-assessment" --- # Issue Assessment Issue Assessment reviews a gflow-cli issue against code, tests, and docs to decide whether the claim is confirmed, needs more info, or is already known. It also checks whether the issue can be verified end to end and drafts a reporter-facing reply. **Install:** ```bash npx degit https://github.com/ffroliva/gflow-cli/tree/develop/skills/issue-assessment ~/.claude/skills/issue-assessment ``` ## README # `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 ``` 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 --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 #: ** (confidence /10) Restated claim: . Findings: - … - … Root cause / hypothesis: . What we need next: - , or - , or - . ``` ### 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 `) or Phase 9 Issue Resolve (`/gflow:issue-resolve `)."** 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`](../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.