Spec: the contract everything else cites

A spec is the document later work is checked against. /blueprint plans against it, /e2e-test derives cases from its criteria, and /revise uses it as the scope fence. So it must be product-level, testable, and stably addressable.

The spec says what and why, in user-observable terms. How belongs to /blueprint. The litmus test: two different implementations can both satisfy it. A technical constraint appears only when it is a genuine product constraint, such as compliance or platform.

Required references

Paths are relative to this file. <plugin root> is two directories above it.

Workflow

1. Orient. Find the repo's existing spec convention: a specs directory, its index, its ID scheme. Read the specs adjacent to this feature. The repo's convention wins. Only where there is none, use the default in references/format.md, and read it now. Decide create against amend. A feature that already has a spec gets an amendment, not a rival document. Say which you chose, and why.
2. Extract. From the request and the repo, collect the users involved and the pain being solved. Collect the current behavior being changed, and the 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. Read ../../assets/writing.md first. Write the overview and goals, the non-goals, and the user-observable behavior. The overview's first sentence says what the feature does for its user. A definition or a status line comes after it, even where the repo's other specs open with one. Non-goals fence every later skill against scope creep, so write them as deliberately as the goals. Then write the acceptance criteria with IDs. Each is a scenario with an observable outcome that a black-box test could execute. "Fast" or "intuitive" is a goal at best, never a criterion. Happy path, edges, and error behavior are all criteria. Feature-local invariants live in the file. A cross-cutting one is proposed for the global invariants doc and flagged. Open questions come last. When amending, new criteria take fresh IDs, removed ones leave holes, and the diff reads 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 do not contradict the goals. Run <plugin root>/scripts/prose-lint.py on the spec file and fix every finding in the text.
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 against 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 or invariants, or the conflict is surfaced.
• The spec file passes prose-lint.py with no findings.
• User sign-off requested before downstream work cites the spec.