Create a GitHub issue (template-compliant, auto-seeded)

What this does

Turns a raw idea into an issue a future contributor can pick up cold: one self-contained description that obeys the project's issue template, then walks the idea from fuzzy to actionable —

1. Brainstorm — frames the problem, lays out 2-3 approaches with trade-offs, recommends one.
2. Spec — the formal design doc for the chosen approach.
3. Implementation plan — bite-sized, testable tasks an engineer (or implement-issue) can execute.

Brainstorm, spec and plan follow the kit's own shared doctrine — ../_shared/brainstorm-and-spec.md and ../_shared/plan-shape.md — so the artifacts match how the project plans work on every machine, with no third-party plugin installed (#324).

Large work does not leave here as one issue. When the plan Step 6 writes would earn the profile's largest effort size, the idea files as a parent plus tracer-bullet children — the parent a plan-less tracking body auto-dev never dispatches, each child a vertical slice with its own plan and its blockers wired as native GitHub dependencies (Step 6's decompose branch; references/decomposition.md, the parent's body per references/tracking-issue.md). --no-split keeps today's single large issue.

Everything lives in the issue body, not comments — deliberately. GitHub's task-list progress meter (the 3 of 8 bar on issue lists / project boards) counts checkboxes in the body only, and implement-issue reads the plan straight from the description. So the trackable plan belongs in the body, where ticking a task moves the needle.

Autonomy contract

Run hands-off. See ADR 0005 for the decision and its scope. The doctrine in _shared/brainstorm-and-spec.md descends from an interactive process (ask one question at a time, stop at approval gates); here you run it in one-shot autonomous mode. Whenever the process would ask or wait for sign-off, pick the most reasonable default, state the assumption inline (a short "Assumptions" note), and keep going. Only stop for a genuine blocker you can't assume past (gh not authenticated, or an idea too vague to even name). Decide; don't hold up the line.

--grill is the single sanctioned exception, and only when the user passed it. The contract above is right because nobody is usually watching — merge-pr Step 6 and the auto-dev workers file issues into an empty room, and a question asked there is the never-wait failure (#187). Passing the flag is the evidence that somebody is there to answer, so it buys exactly one round of questions and nothing more: see ../_shared/grilling.md. Without the flag, nothing about this contract changes — never invent a pause because the idea felt underdetermined.

Inputs

Everything below runs from one default inlet: an idea in the user's own message. Two opt-in inputs change where the idea comes from and whether Step 5 pauses; both are off unless the user typed them, so every unattended caller keeps today's behaviour byte for byte.

Parse these from the request as prose — the skill reads its own arguments, the same way triage-backlog reads --dry-run; there is no argument-parser script. Anything on the line that is not one of these flags is idea text.

A flag is a standalone token at the start or the end of the request, separated by whitespace, never a word inside the idea's own sentence. --grill add X and add X --grill pass the flag; add a --grill mode to X does not — that --grill is idea text, because it sits inside the sentence rather than at either edge. Same test for --seed: a bare --seed with no #N token in that position is not a seed either. This is what keeps an unattended caller (merge-pr Step 6, the auto-dev workers, deliver-issue) from misreading an idea that happens to quote a flag's spelling in its own prose — "let triage-backlog accept --grill the way create-issue does" carries no flag; "do it like --seed #40 does for issues" carries no flag either, since --seed #40 there sits mid-sentence, not at an edge.

The two compose: --seed #N --grill puts the decisions #N leaves open to the user first, then seeds #N with the answers fixed. --force is meaningless without --seed — say so and carry on rather than stopping.

Checklist

Create a task per item and complete in order. For a batch of ideas, run steps 2-8 once per idea.

1. Preconditions — confirm gh works and you're in the repo.
2. Capture the idea(s) — from the user's message; don't interrogate.
3. Check for duplicates, root causes & related issues — don't refile what exists, fold a symptom into the issue that owns its cause, link what's adjacent.
4. Build the template-compliant body fields — read the live issue template and fill it.
5. Brainstorm + Spec — collapsible <details> sections (per _shared/brainstorm-and-spec.md).
6. Implementation plan (per _shared/plan-shape.md) — a visible section whose - [ ] checkboxes feed the progress meter; never inside a <details>. If the plan would earn the largest effort size (and no --no-split): decompose it into a parent plus vertical-slice children instead.
7. Assemble the description, choose labels, create the issue — one body, one "<kit>/scripts/tracker.sh" issue-create (or, with --seed #N, one "<kit>/scripts/tracker.sh" issue-edit-body onto the existing issue and never a create), labels (type + priority + effort + area, plus any sub-area the profile defines) from the profile, then read the issue back. Decomposed: parent first, children in dependency order, then scripts/wire-edges.sh wires the edges in a second pass (still direct gh, per The decomposed variant).
8. Recap — the shared closing shape (../_shared/recap.md, with its Boundary findings block); list each issue with its URL, point the user at /implement-issue. Decomposed: name then number, and hand off to the first frontier child, never the parent.

How to read this skill

One step file at a time, when you reach it — never all up front. Every token loaded here is re-read on every later turn (skills/auto-dev/references/token-economics.md: ~83% of a run's spend is context re-read), so the step bodies live under references/steps/ and the checklist above is the whole of what loads with the skill. Open a step when its checklist item starts; the shared references it names load the same way, from inside that step.

• Step 1 — references/steps/01-preconditions.md · reads _shared/preconditions.md
• Step 2 — references/steps/02-capture-the-idea.md · reads _shared/untrusted-input-boundary.md
• Step 3 — references/steps/03-duplicates-and-root-causes.md · reads _shared/filing-bar.md, _shared/prior-rejections.md, _shared/untrusted-input-boundary.md
• Step 4 — references/steps/04-template-fields.md
• Step 5 — references/steps/05-brainstorm-and-spec.md · reads _shared/brainstorm-and-spec.md, _shared/grilling.md, _shared/test-seams.md
• Step 6 — references/steps/06-implementation-plan.md · reads _shared/plan-shape.md, _shared/test-seams.md
• Step 7 — references/steps/07-assemble-and-create.md
• Step 8 — references/steps/08-recap.md · reads _shared/recap.md

Notes on quality

• Stay template-driven — read the live issue-template YAML each run (location from the profile's Issue templates section; the kit's own templates/issue-forms/feature_request.yml when it names none); don't hardcode fields that drift.
• Ground content in the repo — reference real files, the actual architecture, and the roadmap; generic boilerplate is worthless.
• Respect the architecture invariant — shape specs/plans to the profile's Architecture grain so a plan reads like it belongs here.
• The plan is a tracked checklist, not an essay — preserve plan-shape.md's - [ ] checkboxes into the body and keep the section visible; flattened-to-prose or hidden-in-<details> loses its job and its place in the progress meter.
• A tracking parent has no plan, on purpose. Zero - [ ], no ### Task, no Implementation plan string — that absence is the mechanism that keeps auto-dev from dispatching a job no single context can hold. Step 7's readback refuses a parent that trips it; never "help" by adding a checklist to the parent.
• The Spec's contract is a promise, not decoration — acceptance criteria are numbered (never - [ ], which the checkbox readback and tick-plan.sh would count), each is checkable without reading the diff, and "Out of scope" names something quotable rather than staying empty. See ../_shared/test-seams.md for the seam doctrine the Testing decisions heading and the plan's Seams under test: line both draw on.