| 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 |
