create-issue git:20260911.257f7edA

Immutable. This exact content is served forever at /api/v1/blob/45265081b7f0d9ef.

---
name: create-issue
description: >-
  Create a fully-seeded GitHub issue — not a bare `gh issue create`: template-compliant, carrying a
  brainstorm → spec → implementation-plan trail so a contributor can pick it up cold. ALWAYS reach
  for this whenever the user wants to open, file, add, raise, log, or track a NEW issue / feature
  request / idea / ticket / backlog item — "track this idea", "make a ticket", « ouvre une issue
  pour X », « crée un ticket pour ça », or batches of several ideas at once. Also PLANS AN EXISTING
  raw issue via `--seed #N` ("give issue 42 a plan"). Does NOT apply to otherwise managing existing
  issues (commenting, closing, listing), or to standalone brainstorming with no issue to file.
license: MIT
compatibility: >-
  Requires an authenticated gh CLI. Reads the committed repo profile
  (.claude/skills/repo-profile.md) generated by profile-repo. Self-contained: the brainstorm,
  spec and plan doctrines it follows ship under skills/_shared/, no third-party plugin needed.
metadata:
  author: Philippe Matray
  suite: ai-migration-kit
---

# 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`](../_shared/brainstorm-and-spec.md) and
[`../_shared/plan-shape.md`](../_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`](references/decomposition.md), the parent's body per
[`references/tracking-issue.md`](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](../../docs/adr/0005-the-lifecycle-skills-run-hands-off-triage-backlog-does-not.md) 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`](../_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.

| Input | Effect | Default |
|---|---|---|
| `<idea…>` | today's path — file a NEW issue from the idea in the request | — |
| `--seed #N` | plan the **existing** issue #N in place instead of filing a new one; Steps 2, 3, 4, 7 and 8 take their seed branch | off |
| `--grill` | one interview round on the frontier of design decisions, before Step 5 writes the Spec | off |
| `--force` | with `--seed` only: re-seed an issue that already carries a `## 🛠️ Implementation plan` | off |
| `--no-split` | file a plan that would earn the largest effort size as ONE issue, exactly as before, instead of taking Step 6's decompose branch | off |

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 `gh issue create` (or, with `--seed #N`, one `gh issue edit` 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.
8. **Recap** — the shared closing shape ([`../_shared/recap.md`](../_shared/recap.md), with its [Boundary findings block](../_shared/recap.md#the-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`](references/steps/01-preconditions.md) · reads [`_shared/preconditions.md`](../_shared/preconditions.md)
- Step 2 — [`references/steps/02-capture-the-idea.md`](references/steps/02-capture-the-idea.md) · reads [`_shared/untrusted-input-boundary.md`](../_shared/untrusted-input-boundary.md)
- Step 3 — [`references/steps/03-duplicates-and-root-causes.md`](references/steps/03-duplicates-and-root-causes.md) · reads [`_shared/filing-bar.md`](../_shared/filing-bar.md), [`_shared/prior-rejections.md`](../_shared/prior-rejections.md), [`_shared/untrusted-input-boundary.md`](../_shared/untrusted-input-boundary.md)
- Step 4 — [`references/steps/04-template-fields.md`](references/steps/04-template-fields.md)
- Step 5 — [`references/steps/05-brainstorm-and-spec.md`](references/steps/05-brainstorm-and-spec.md) · reads [`_shared/brainstorm-and-spec.md`](../_shared/brainstorm-and-spec.md), [`_shared/grilling.md`](../_shared/grilling.md), [`_shared/test-seams.md`](../_shared/test-seams.md)
- Step 6 — [`references/steps/06-implementation-plan.md`](references/steps/06-implementation-plan.md) · reads [`_shared/plan-shape.md`](../_shared/plan-shape.md), [`_shared/test-seams.md`](../_shared/test-seams.md)
- Step 7 — [`references/steps/07-assemble-and-create.md`](references/steps/07-assemble-and-create.md)
- Step 8 — [`references/steps/08-recap.md`](references/steps/08-recap.md) · reads [`_shared/recap.md`](../_shared/recap.md)

## Notes on quality

- **Stay template-driven** — read `.github/ISSUE_TEMPLATE/*.yml` each run; 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`](../_shared/test-seams.md) for the seam doctrine the `Testing decisions` heading and the plan's `Seams under test:` line both draw on.