write-ai-ready-issue
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.
orbi-build · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add orbi-build/orbi --skill write-ai-ready-issue技能说明
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/<owner>/<repo>/contents/<path> \
-H "Accept: application/vnd.github.raw"
gh issue list --limit 200 --state all --search "<keywords>"
gh pr list --limit 200 --state all --search "<keywords>"
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.
- 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. 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 — <question>
- <label> (Recommended): <one sentence of what it means>
- <label>: <one sentence of what it means>
A person answers them in their own words; the agent drafts from those answers.
Full form
Sections, in this order:
Request— the person's words, quoted verbatim.- `Current sta