AI Spec

Write the spec

What it produces

specs/NNN-slug/spec.md, committed in the user's repository and visible in their diff. It is a decision record, not code, a plan or permission the agent gave itself.

The tier to ask for

Spec writing is mechanical once the research has done the hard thinking; ask the low tier, the model the repository's [models] section configures for it — never a model name coded here, and never a provider the repository did not choose. model_router maps research and spec to the low tier; if the pin leaves it unconfigured, fall back to default_tier. Say which tier you ran on so the command event's tier_model can be read against reality.

Procedure

0. Validate the intake and reach shared understanding before any discovery (spec 037 / B-037-3, spec 048): read references/intake.md first, then the goal, constraints and acceptance; ask only what the environment cannot answer, keep a live draft with a TODO per gap from the first answer, and do not scaffold until the owner confirms the two-sentence plain-words read-back; under an unattended goal the run records that read-back as unconfirmed and carries on. The input is the contract: a malformed goal produces a malformed spec.

1. Read CONSTITUTION.md, the related records and repository evidence and current primary sources relevant to the decision before asking anyone. State what was read, what is true now and what remains unknown. Never infer a control from its documentation alone. If CONSTITUTION.md is absent or incomplete, the spec records what is missing rather than assuming it exists — a repo without it is a repo without the framework's identity.

2. State the problem in words a non-technical reader can follow. Separate fixed constraints, current facts, intended outcomes and the harm of leaving it unchanged.

3. Present exactly three real options. For each, say what it gives, costs, risks and rules out; do not invent a weak option merely to lose.

4. Recommend one, explain why the others lose, then challenge the recommendation once with the strongest realistic failure case. Revise it or keep it and say why.

5. Record assumptions and unresolved risks separately. Do not turn either into fact or an accepted risk, and do not invent an owner, approval or green result.

6. Give observable BDD examples for the important success, denial and undecidable paths, using Given/When/Then and outcomes somebody can check.

7. Ask only questions whose answers change the decision, after presenting the evidence and provisional recommendation. A human answer overrides inference; update the options, recommendation and risks it changes rather than appending a contradictory answer.

8. Create the draft with ai-eng spec new <slug>; add --ref owner/repo#45 only when that is the real work item. If this supersedes shipped work, create a new spec, link the old record and explain the change; never rewrite history.

9. Architecture advice belongs inside the options, never beside them. Where a boundary, a dependency, a duplicated source of truth or the cost of reversing it decides between two options, say so in the option that carries it. A separate architectural opinion nobody has to answer is the advisor this project chose not to build.

10. Keep decisions in their spec unless they constrain future specs. For the ones that do — architectural and cross-cutting: a boundary (API, auth, storage) or a global convention later specs must know and respect — list them under ## Decisions marked - [X] and promote with ai-eng decide "<title>"; the verb promotes only marked titles, and proposal is not approval. Everything else stays inside the spec, which is its record. Leave every production-ready box unticked until the named command supplies fresh evidence.

11. When the critics report, fold them in place: the grill's questions into ## Grill and the council's gaps, cuts and refutations into ## Council, each section opening with its ran: round <n>, <date> — <n> min declaration, and revise the options, decision and risks those findings attacked rather than answering beside them.

Authority boundary

Without a person, choose only a reversible, least-scope option within existing permissions and record the permission and reversibility. Never expand a write, execution, network or publication boundary because the preferred option needs it.

For an irreversible, high-risk, contradictory or cross-cutting decision without an accountable human decision or exact preapproved policy, return INCOMPLETE. Record what authority is missing with ai-eng report blocked, so the page in docs/ shows it and the person who is not at the keyboard can see it — say what is missing, never that it arrived. Then stop before plan, code, publication or risk acceptance.

A fresh reviewer may find defects or recommend escalation, but never grants authority, accepts risk or approves its own work. More reviewers do not change this boundary.

If CONSTITUTION.md is absent or incomplete, discovery may prepare it, but writing the project identity is cross-cutting and requires the same authority. Never overwrite one.

Done when

• The spec says what is wrong, what evidence supports it, what could be done and why the recommendation survived its challenge.
• Assumptions, unresolved risks and observable BDD examples are explicit.
• The authority basis is named, or the result is INCOMPLETE with the missing decision.
• The human was handed ai-eng report view --spec <NNN>'s file:// link beside the Markdown, so the page they approve from carries the digests the ADR will name.

What this is not

Not a discussion transcript, implementation or risk acceptance. Delete empty ceremony; keep the evidence and decisions a future reader must be able to audit.

• "Only one option is worth considering, so two options would be theatre" — the procedure demands exactly three real options and forbids inventing a weak one to lose, because the comparison is what makes the recommendation auditable.