spec

name	spec
description	Author or revise a work item's spec at docs/spec/<id>.md before any code is written, then run it through the spec gate. Use when starting a new work item, when a spec needs revision after a spec-gate rejection, or when acceptance criteria must be defined. Produces a fully-signed spec — Goal, Non-goals, evidence-cited claims, stable spec-item IDs, and frozen executable acceptance criteria.

A spec is the written commitment for one work item (one branch work/<id>). It is authored before code and reviewed adversarially by the spec-gate subagent. Code does not start until the gate passes. See docs/process.md.

Author the spec

Copy this skill's references/spec-template.md to docs/spec/<id>.md and complete every section. The gate fails a spec that is missing any of them.

• Goal — what this work item delivers, bounded.
• Non-goals — what's explicitly out of scope. Required: without them the gate cannot distinguish an authorized deferral from a silent scope cut.
• Evidence — every non-trivial claim cites a concluded spike (SPIKE-<n>), a code path (file:line), or a doc. Use the spike skill for uncertainties.
• Spec items — each normative requirement gets a stable ID (<PREFIX>-<n>) so it is citable in code (an implements <PREFIX>-1 marker in a comment) and traceable.
• Acceptance criteria — executable commands (prefer pixi run tasks), written verbatim in a fenced block and frozen here. Each ties to a spec item. The impl gate re-runs them itself; never author criteria that pass without exercising real behavior.

A spec is fully signed only when every item has all three of: evidence, a criterion, and spec-gate sign-off.

Run the spec gate

Invoke the spec-gate subagent to review the spec (and every ADR it depends on) adversarially. It hunts for: unauthorized scope cuts, uncited claims, open questions, and infeasibility. On a fail, address each finding by editing the spec (and/or concluding more spikes) and re-run — do not start implementation.

On a pass, present the spec to the human for sign-off. Implementation begins only after the human approves the spec — spec→impl is a human gate, not just an AI one.

Back-edge

If implementation reveals the spec is wrong, return here: edit the spec and re-run the spec gate before continuing. The spec is the contract; keep it true.