File Issue

Step 1 — Auto-classify (recommend, then confirm)

Derive the type + labels from the issue's content automatically — don't ask the user to pick from scratch. Read the idea, match it against the repo's existing labels (Step 0), and propose a classification; the user confirms or overrides at the Step 4 gate (for a batch, one confirmation covers the whole table).

How to classify from content:

• bug — words like "broken / throws / crashes / regression / doesn't work", or a repro of wrong behavior → bug.
• enhancement — "add / support / it would be nice / feature" → enhancement.
• documentation — only docs/README/comments change → documentation.
• good first issue — additionally apply when the task is self-contained, low-risk, and a meaningful mini-project (see the shape rubric below). Usually paired with enhancement.
• help wanted — maintainer wants outside help but it's not necessarily beginner-safe.

Only emit labels that exist in the repo (Step 0). If content suggests a label the repo lacks, surface it rather than silently dropping or inventing one. When classification is genuinely ambiguous, state your best guess + the runner-up so the confirm step is a quick yes/no, not an open question.

The issue's shape also drives the body template (Step 3):

• good first issue — self-contained, low-risk, meaningful (a mini-project a contributor can own end-to-end), not a micro-cleanup. Good signals: greenfield feature with no existing infra (e.g. i18n, shell completions), a self-contained new subcommand (rove doctor), or a repeatable visual contribution (a new theme). Anti-signal: "add a unit test for X" / "extract a constant" — too small to be worth an external contributor's onboarding cost; the user has rejected these. Aim for tasks that touch 1–3 files but deliver a complete, satisfying chunk of value.
• bug — reproducible defect. Body leads with repro steps + expected vs actual.
• enhancement — a feature/improvement for the maintainers, not necessarily beginner-friendly.

Most low-priority hand-off tasks are good first issue + enhancement together.

Step 2 — Verify every pointer (mandatory)

Before writing the body, confirm each claim against the tree. Cheap checks that prevent filing fiction:

# file exists + size/shape is what you think
ls -la packages/rove/src/<path>
# the function/string/registry you're pointing at really lives there
grep -rn "BUNDLED_THEMES" packages/rove/src/tui/context/theme/
# the thing you claim is MISSING really is absent (greenfield framing)
find packages -iname '*completion*' | grep -v node_modules    # empty => "no completions exist"

If you spawned an Explore agent to find candidates, re-verify its file paths yourself — exploration output can carry typo'd or doubled paths (e.g. packages/rove/packages/rove/...). Never paste an unverified path into an issue.

For greenfield framing ("there is no X today"), prove the absence with a find/grep that comes back empty — that sentence is load-bearing for a contributor.

Step 3 — Draft the body

Use this template for a good first issue / enhancement (trim sections that don't apply):

## Background
<1–3 sentences: what exists today, why this matters, what's missing. State greenfield
absence explicitly if true: "the repo has no X infrastructure at all.">

## Why it's beginner-friendly      ← only for good first issue
- <what knowledge is NOT required — e.g. "does not touch daemon/engine/orchestrator">
- <why it's safely incremental / splittable>

## Scope
1. <concrete step with the exact file path to add/edit>
2. <next step, with the registry/wiring point named>
3. <docs/README update if user-facing>

## Important notes        ← constraints that would otherwise trip a newcomer
- <e.g. "engine-owned copy is not translated — comes from AIEngine.identity">
- <e.g. "do not change DEFAULT_THEME = 'claude'">

## Acceptance
- <observable pass condition>
- <exit-code / test / screenshot expectation>

For a bug, lead instead with:

## Repro
1. <steps>

## Expected vs actual
- Expected: …
- Actual: …

## Environment / pointers
- <version, OS, relevant file:line>

Style: terse, concrete, second-person imperative for scope steps. Reference code as file_path:line so it's clickable. Link Rove docs with repo-relative paths (docs/ARCHITECTURE.md).

Step 4 — Confirm, then file

Show the user the drafted title(s) + body(ies) and the labels you'll apply. For a single obvious issue you may file directly; for a batch, confirm the set first (an AskUserQuestion with "file all / show full drafts / pick a subset" works well).

File with a heredoc to keep Markdown intact:

gh issue create \
  --label "good first issue" --label "enhancement" \
  --title "feat: <concise imperative title>" \
  --body "$(cat <<'EOF'
<body from Step 3>
EOF
)"

gh issue create prints the new issue URL — collect them and report back as a table (number, title, URL). To revise after filing, use gh issue edit <n> --title … --body … (same heredoc pattern); editing needs no re-confirmation.

Step 5 — Report

Summarize what was filed (table of #/title/URL) and offer obvious follow-ups only if they have a concrete hook: assign a milestone, split a multi-part issue, or add a few more candidates at the same scale. Don't over-offer.