new-issue

name

new-issue

description

Use when the user says "new issue", "create an issue", "file an issue", "/new-issue", or asks to turn a bug, idea, or discussion into a GitHub issue. Takes an optional description of what the issue should cover; with no input, derives the issue from what was discussed in the current conversation. Verifies claims against the code before filing and produces a complete, complexity-scored issue — never a stub.

new-issue

Create a fully-specified GitHub issue from the user's prompt — or, when nothing is prompted, from what was just discussed in the conversation. The deliverable is a filed issue that someone (human or agent) could pick up cold and implement correctly: concrete problem statement, goal, approach, acceptance criteria, complexity score, attribution footer. Never file a placeholder, stub, or empty-bodied issue — no exceptions.

Spec the absolute-best solution — full stop. When the issue proposes an approach, derive it from first principles as if cost, compute, time, effort, manpower, token spend, code volume, and blast radius were unlimited — none of these are factors and none may narrow the option space. The only constraints that override "best" are correctness and safety (money, data integrity, security, auto-protective mechanisms — safety-class gaps are never acceptable, however "low-risk"). Don't spec the tidier/less-code design when it leaves a correctness or safety gap, and don't scope the issue down to what seems cheap to build.

Input

The user provides one of:

• A description of the bug/feature/task to file — use it as the source, but still ground it in code (below).
• Nothing — derive the issue from the current conversation: the bug just diagnosed, the design just discussed, the follow-up just named. If the conversation contains several distinct candidates, file the one the discussion converged on; name the others and offer to file them (each fully specified) rather than bundling.
• Optionally owner/repo or a repo path when the issue belongs somewhere other than the current checkout (gh issue create -R owner/repo).

Steps

1. Establish the repo and check for duplicates

Confirm which repo the issue belongs to (gh repo view --json nameWithOwner). Then search for an existing issue or PR already covering it — filing a duplicate wastes a cycle:

gh issue list --state open --search "<keywords>"
gh pr list --state open --search "<keywords>"

A genuine hit → stop and surface it (offer to update/comment on the existing issue instead). A passing mention doesn't count.

2. Ground every claim in the code — before writing a word

The issue's factual claims about current behavior are claims, not notes — the same standard validate-issue holds authors to applies to you as the author. For each behavior the issue will assert, trace the code path and keep the file:line; a claim you can't trace is phrased as unverified ("appears to…", "needs confirmation"), never stated as fact. If the issue came from this conversation, don't transcribe from memory — re-check the load-bearing citations against the actual files; conversation recollection goes stale exactly like an author's prose does.

If the working tree is on a divergent or stale branch, trace against origin/<default> (git show "origin/$DEFAULT":<path>) so citations match what an implementer will check out.

3. Design the approach (non-trivial issues)

For anything beyond a localized bugfix, spec the approach the way validate-issue's architecture pass would judge it — so the issue passes its own future validation:

• Placement and ownership — which layer/component owns the change; for shared state name the owner, lifetime, medium, population timing, consumer contract, and failure policy.
• Touch-set — grep the affected symbols and name every site that must change (read/write/default/validate/serialize), not just the obvious one.
• Conventions — match the repo's existing patterns (CLAUDE.md, guardrails, existing helpers) over new infrastructure; respect documented invariants (single-writer, fail-closed, "X never into Y").
• Best over cheap — per the principle above: if the correct design is bigger than the convenient one, spec the correct design and let the complexity score say so.

Include acceptance criteria an implementer can verify: observable behavior, tests that must exist (regression test for a bug, red → green), parity surfaces that must match.

4. Score complexity

Score the work to implement the fix correctly, including tests using the canonical formula in validate-issue step 6 (load that skill or mirror it exactly): five axes 0–4 → Capability (0–3 from Risk/Uncertainty + Coupling≥3 bump) and Volume (0–24 from Scope+Coupling+Verification) → score = 25 × Capability + Volume. The score is a model + effort routing signal, not a time estimate — never put durations in the issue. Derive axes from the concrete touch-set in step 3, not vibes; count the surface that hides from the diff (tests, parity/offline paths, migrations, docs).

From the Capability band, also fix the fableplan signal: fableplan: yes only when Capability = 2 (score 50–74 — Opus-class build, planned by Fable 5 first); no for every other band (0–1 need no separate plan; band 3 is built by Fable 5 directly). It goes on the rationale line in step 6 — always explicit, never omitted.

5. Scope check — one issue or several?

If the deliverables are separable — parts that each land in their own PR, pass their own tests, and deliver value alone — don't bundle: file the core issue and tell the user which parts warrant their own issues (each fully specified before filing, or tracked as a checklist in the parent until ready — never stubs).

6. Compose and file

Title: [C<score>] <title> — the title is a clear, plain-language sentence understandable to an average 18-year-old (ELI18) — it states the bug or deliverable precisely (component + behavior) without unexplained jargon, no vague "improve X".

Body structure:

**Complexity: <score>/100** — Capability <k> (<driver>); Volume <v> — <model/effort from band> · fableplan: <yes|no>

## Problem
<Current behavior, grounded with file:line citations from step 2. What's wrong or missing and why it matters.>

## Goal
<The outcome in plain language — what's true after this lands.>

## Approach
<The optimal design from step 3: placement, touch-set, key decisions. Explicit that correctness/safety outrank diff size.>

## Acceptance criteria
- <observable behavior / test that must pass>
- <…>

---
Created with LLM: <current model> | <effort> | Harness: <harness>

The complexity rationale is the first line of the body and matches the title prefix — same Capability/Volume form as github-issue-format (round-trips with the [C<score>] band, e.g. [C58] → Capability 2 (…); Volume 8), and always ends with the explicit fableplan signal from step 4 (· fableplan: yes iff Capability 2). The footer is the final lines, preceded by --- on its own line — Created verb, <effort> one of medium/high/xhigh (default high, never low), <harness> = Claude Code for an interactive session. No Co-authored-by. Project precedence: a repo CLAUDE.md that defines its own issue/footer format overrides this default.

File it:

gh issue create --title "[C<score>] <title>" --body-file <body-file>

Add --label/--assignee only when the repo visibly uses them (gh label list) and the fit is unambiguous.

7. Report

Terse: issue URL, number, one-line summary of what it covers, complexity score, and any candidate follow-ups you did not file (with why). Offer "validate issue" / "work on issue" as next steps in one line.

When the issue's signal is fableplan: yes, also ask the user explicitly — one line, e.g. "This issue is Capability 2 — want a Fable 5 plan posted before building? (fableplan)" — and let the user decide; don't launch fableplan unprompted, and don't silently drop the recommendation. (Autonomous loop skills that wrap this one parse the signal and apply their own documented gates instead of asking.)

Guardrails

Situation	Action
Tempted to file with a thin body "to capture it quickly"	Don't — every issue is complete at creation; if it isn't ready to spec, tell the user and track it in notes/parent instead
No prompt and the conversation discussed several things	File the converged one; name the rest, don't bundle
A claim about current behavior you haven't traced	Trace it or phrase it as unverified — never state a guess as fact
Issue derived from conversation memory	Re-verify load-bearing file:line citations against the actual code before filing
An existing open issue/PR already covers it	Stop; surface it and offer to update/comment instead
The cheap design and the correct design diverge	Spec the correct one; cost, effort, and blast radius are not factors — only correctness and safety constrain
Touches money / data integrity / security / auto-protective logic	Spec the safest correct design from first principles; surface the risk in the body and Risk axis
Tempted to include a time/effort estimate	Don't — complexity score only (Capability band + Volume), described via the axes
Repo has its own issue template or CLAUDE.md issue format	Follow the repo's format; it overrides this default