issue-assessment

Files (1)

• SKILL.md

SKILL.md (first lines)

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

From ffroliva/gflow-cli, MIT.

More from ffroliva/gflow-cli