--- name: write-ai-ready-issue description: Use when the user wants to turn the current discussion into a GitHub Issue, wants a task done without watching it, asks whether an Issue is clear enough for an AI agent to deliver, or wants to split a big task into several Issues. Reads the repository read-only first, drafts only what the person asked for, runs an independent fidelity pass, and hands the Issue to Orbi when Orbi already delivers the target repository. --- # Write an ai-ready Issue Turn the person's request into a GitHub Issue an AI agent can deliver without supervision: grounded in the code that exists today, and asking for exactly what the person asked for. This works for anyone, whether or not they use Orbi; only the final hand-off step needs Orbi. The bar for a written Issue is the 12 factors at https://aiready.sh/. Prior art this skill borrows from: superpowers `brainstorming` (size the task before writing), mattpocock `grilling` (sharpening a request with pointed questions), Spec Kit `specify` (at most three clarifications, assumptions written down), OpenSpec (WHEN/THEN acceptance), cc-sdd `kiro-discovery` (choose the route before writing). ## Fidelity comes first - The User outcome restates the request in observable terms: what happens, for whom, when. It never grows the request. - Acceptance holds only the requested behaviour, plus at most one failure path of that same behaviour (what the person sees when it fails). Everything else — hardening, adjacent cleanup, "while we are here" — goes under `Not included (suggestions)`, one line each. - A repository observation is evidence, never a requirement. How many lines the file has today, or which line the new one would become, is at most a line under `Current state`. For a preserve-and-append request (append one line, keep the existing content, change no other file), express the relative change — the sentence appended and the existing content untouched — not a total line count the person never named. A quantity the person stated ("exactly 17 lines") is their requirement and stays. - A request with two readings does not become the bigger reading. Take the smallest reading and record that reading under `Assumptions` (see *Draft first*). - Behaviour that already exists is reported as existing under `Current state`. Never write an acceptance item for making something work that already works. - Never widen the scope to make the Issue look complete. ## Read before writing, read-only Read the repository before drafting. Read-only means: no branch, no edit, no commit, no test run. Read the files the change would touch and their callers, the related tests, `AGENTS.md`, the docs that describe the current behaviour, and the open Issues and PRs that may already cover the request. With a checkout, read the files directly. Without one, read through the GitHub API and search the tracker: ``` gh api repos///contents/ \ -H "Accept: application/vnd.github.raw" gh issue list --limit 200 --state all --search "" gh pr list --limit 200 --state all --search "" ``` Never ask the person for a fact the code, docs or open Issues can answer, and never ask which of several reasonable options to take — that is a decision: take the default and record it under `Assumptions` (see *Draft first*). ## Route first, in one line Before drafting, state the route in one line, then follow it: - **Already covered** — an Issue, PR or docs page already does this: link it and stop. - **No repository change needed** — the request is about how the person works, not the repository: say so and stop. A docs or config change is a repository change, so it is not this route. When the person explicitly asks for no code change ("just review it and tell me", "only explain", "don't touch the code"), this is the route even when the reading finds real defects: answer with a reply alone, in the person's language, one line each of what the reading found worth fixing, and say that Orbi delivers by opening a pull request, so the person can name one item for Orbi to fix. Create no Issue. - **Small** — one observable behaviour in a handful of files: short form. - **Normal** — everything else: full form. - **Too big** — more than one independently mergeable result: propose the vertical slices and draft EVERY slice, one Issue each, with their order (`after`) recorded. A request drafted as one Issue whose acceptance list covers independent deliverables is stopped by Orbi's pre-work check as "more than one outcome"; several Issues with an order is the deliverable shape. ## Draft first If reading the code shows the request cannot be done as asked (the file it is about is empty or missing, or the thing it would change does not exist), draft the nearest version of the request that the code can actually deliver, and make the first line of the Issue's `Assumptions` section say what you changed and why. The nearest-deliverable rule applies only to a request that asks for a change: a request not to change any code takes the no-repository-change route above and ends with a reply alone. Never write a draft whose only possible delivery changes no file. Draft the Issue before asking anything. A disagreement the agent can settle itself is not a question — it is a line under `Assumptions`. Every other disagreement — which library, font or place to use, what to leave out, how to word that deliverable version — is the same: choose the most reasonable default, write one line under `Assumptions` in each Issue saying what you chose and why, and draft. Ask the person only when, after reading the code, the request itself still does not say what to build — it is empty or contradicts itself — and no deliverable default version can be written. Then ask at most three questions in one reply. Each question carries a header of one to three words naming the decision and 2 to 4 options, every option a label of one to five words plus one sentence of what it means or its trade-off. When one option is the reasonable default, it comes first and its label ends with `(Recommended)`. Never add an "Other" option: the person's own answer is always allowed. Never say the person chose the recommended option. ``` Q1 — -