Immutable. This exact content is served forever at /api/v1/blob/6cf8c8e87bccf3bc.
--- name: spec description: Turn a fuzzy feature request into a reviewable product spec — goals, non-goals, testable acceptance criteria with stable IDs, invariants — that later skills cite by path and ID. Use when the user says "/spec", "spec this out", "write a product spec", "turn this idea into requirements", or brings a feature request that needs a contract before planning or building. --- # Spec: the contract everything else cites The point is a document later work can be *checked against*: `/blueprint` cross-validates its plan with it, `/e2e-test` derives cases from its criteria, `/revise` uses it as the scope fence. That only works if the spec is product-level, testable, and stably addressable — which is what this skill enforces. `/spec` says what and why; how belongs to `/blueprint`. ## Principles - **WHAT and WHY, never HOW.** Everything is stated in user-observable terms. Litmus: two different implementations should both be able to satisfy the spec. Technical constraints appear only when they are genuine product constraints (compliance, platform), not design preferences. - **Testable or it isn't a criterion.** Each acceptance criterion is a concrete scenario with an observable outcome — something an end-to-end test could execute black-box. "The feature should be fast/intuitive/robust" is a goal at best, never a criterion. - **Stable IDs, append-only.** Criteria carry IDs that later skills cite; IDs are never renumbered or reused, and deletions leave holes. See `references/format.md`. - **Never invent answers.** Unknowns become marked assumptions or open questions; blocking questions go to the user, batched, once. - **Non-goals are load-bearing.** What the feature deliberately does not do is the fence against scope creep in every later skill — write them as deliberately as the goals. ## Workflow 1. **Orient.** Find the repo's existing spec convention — a specs directory, its index, its ID scheme — and read the specs adjacent to this feature. The repo's convention wins; only where there is none, use the default in **`references/format.md` — read it now.** Decide create vs amend: a feature that already has a spec gets an amendment, not a rival document. 2. **Extract.** From the request and the repo: the users involved, the pain being solved, current behavior being changed, adjacent specs and invariants touched. Distill candidate goals and constraints; inventory the unknowns. 3. **Ask what blocks the shape.** Split the unknowns: answers that change the spec's structure (who it serves, where its boundary sits, what success is) are asked as one batched round of questions — then wait. Everything else proceeds as a marked assumption or an open question in the draft. Zero silent inventions. 4. **Draft** per the format: overview and goals, non-goals, user-observable behavior, acceptance criteria as ordered testable steps with IDs — happy path, edges, and error behavior all as criteria — invariants (feature-local in the file; a cross-cutting one proposed for the global invariants doc, flagged), and open questions last. When amending: new criteria take fresh IDs, removed ones leave holes, and the diff should read as "what changed about the product's contract". 5. **Cross-check.** Every goal is covered by at least one criterion; every criterion is black-box testable; nothing contradicts an existing spec or invariant — a conflict is surfaced to the user, never silently overridden in either direction; non-goals don't contradict the goals. 6. **Present and gate.** Deliver the spec with its open questions surfaced; a spec is a contract, so the user signs off before anything downstream builds on it. Committing and PR-ing it is `/submit`'s job, on request. ## Definition of done - [ ] Repo convention honored, or the default format used and said so; create vs amend decided deliberately. - [ ] Blocking questions asked once, batched; every remaining unknown is a marked assumption or open question — none invented. - [ ] Every criterion has a stable ID, an ordered scenario, and an observable outcome; IDs append-only. - [ ] Goals each covered by a criterion; edges and error behavior specified, not implied. - [ ] No implementation content; non-goals present and real. - [ ] No contradiction with existing specs/invariants, or the conflict is surfaced. - [ ] User sign-off requested before downstream work cites the spec. ## Related skills `/blueprint` plans against the spec · `/e2e-test` tests from its criteria · `/revise` uses it as the scope fence · `/repo-docs` sets up the docs layout specs live in.