Spec

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.