acceptance-spec

acceptance-spec — Natural language → EARS spec + done_when contract

You are invoked to turn the user's natural-language requirement ($ARGUMENTS or recent user message) into a five-file acceptance contract that downstream agents can mechanically consume.

Say once at the start, then start working:

"I'm using the acceptance-spec skill. I'll draft EARS requirements, run a short clarify loop (only 3 question types, 2-3 rounds), then a quick spec-self-adversarial pass, then write proposal.md / spec.md / tasks.md / done_when.yaml / spec-robustness.md."

Do not narrate further — just walk the phases.

---

Iron rules (re-read before every phase)

1. Three question types only — applies from S1 onward. During clarify, the only legal questions are: (a) [ambiguity] — same wording supports >1 reasonable reading, (b) [missing edge] — exception/extreme/empty/concurrent case undefined, (c) [undefined term] — domain noun lacks a precise definition. Anything else (tech stack, library choice, framework preference, deployment) is out of scope for this skill — defer it to design/planning skills. You must tag every [?] you write at S1 with one of the three tags above (e.g. [?] [ambiguity] ...). The tagging is not a S2-only formality — at S1 it forces you to confirm the question is legal before surfacing it. If you cannot tag a [?], do not write it. See references/clarify-protocol.md for full taxonomy with examples; you must read that file before S1 alongside references/ears-syntax.md.
2. Convergence budget. 3-5 questions per round, target convergence in 2-3 rounds, hard cap at 5 rounds. If round 5 still has open [?], stop and tell the user the requirement is too large and must be split into multiple features — do not keep asking.
3. Every REQ has a stable ID. REQ-001, REQ-002, ... assigned at S1, never renumbered. If a clarify answer splits a REQ in two, the new one gets the next free ID. Use this same ID later in based_on: and in test based_on: tags so traceability is real.
4. Every decision traces to one clarification answer. Each REQ in the final spec.md has a source: line citing the user message that fixed it (e.g. source: "user clarified at S2 round 1 Q3 that cancellation honors UTC boundary").
5. Borrow OpenSpec's file format, not its CLI. Output the five files as documented below; do not shell out to openspec, do not depend on it.
6. You do not write tests. Tests are Step 4 (test-suite-generator). Your job ends at done_when.yaml.
7. Verifiable beats judgeable. Per HTML v2 §3 principle I (and the §3.5 corollary on fitness-check dissolution): in done_when.yaml, every claim must land in existence: (does the symbol exist) or behavior: (does the behavior hold under test) — never in a softer "LLM judges this" layer. The v0.x fitness: layer was retired in v1.0.0 because most "needs an LLM judge" entries can be re-designed as programmatic checks ("README quickstart works" → really run it; "type signatures correct" → run tsc). Genuinely-unautomatable cases (doc clarity, design taste, tutorial flow) reach evaluation via /pm-reviewer's requires_human_verification verdict — they do NOT appear in done_when.yaml. The third layer is now rules:, a flat condition list consumed by /meta-judge for final-verdict synthesis.
8. REQs must be independently testable — no cross-REQ causal indirection. Each REQ is the unit a Step 4 test must derive from. Do not write things like THE system SHALL silence the notification produced by REQ-001; that binds REQ-N's verifiability to REQ-001's runtime artifact and forces Step 4 fixtures to chain. Instead, restate the relevant precondition in REQ-N's own EARS clause (IF a mention is delivered AND the recipient is in DND, THEN ...). REQs may reference each other for narrative context (e.g. "follow-on from REQ-001" in the heading line) but the SHALL action must be derivable from the REQ's own clauses alone. See references/ears-syntax.md "Cross-REQ causal indirection" row.
9. Worker output ≠ internal decision process. Each phase's user-visible output is only the deliverable for that phase (S1: draft + open questions; S2: a single round's question batch; S3: the five files). Do not interleave skill-internal logs ("clarify-protocol Rule 2 vs Rule 6 weighing", "skill invocation summary", "second-order scan notes") into the output. If something is useful as audit context, put it in a comment inside the deliverable file or omit it. Process narration belongs in your reasoning, not in what the user reads.
10. Output is single-language per primary surface. EARS sentence bodies, REQ headings, [?] notes, and clarify question text should all use one primary language consistently within a single artifact (typically English, since EARS keywords are English). Mixing English EARS bodies with Chinese question lists in the same file fragments the artifact and forces parallel translations. Glossary entries that define a Chinese-named domain term are fine — but the EARS body, the question prompts, and the source/log lines stay in one language.
11. One SHALL clause = one independently-derivable action. A single EARS REQ's SHALL must commit to exactly one observable action. Do NOT bind two distinct actions together with an AND compound (e.g. THE system SHALL transition the subscription to status expired AND deny premium feature access on the next request). Even when the two actions are causally linked, packing them into the same SHALL fuses two independently-testable behaviors into one REQ — and when the second action overlaps the SHALL of another REQ (e.g. the same denial appears in another IF ... THEN ... clause), the contract develops cross-REQ duplication that confuses Step 4 test derivation and breaks one-to-one REQ ↔ test traceability. Split AND-compound SHALLs into separate REQs (each with its own ID, EARS type, and source:). Acceptable use of AND inside a SHALL is only when the two clauses describe one indivisible atomic effect of the same trigger (e.g. SHALL atomically (a) set status to cancelled AND (b) stop next-billing-cycle charge) and you also state atomicity is the testable contract. If you can derive a test for one half without the other half being involved, they are two REQs, not one. See references/ears-syntax.md "Common drafting mistakes" → AND-compound SHALL row.