to-spec

name	to-spec
description	Run when the user says "write a spec", "turn this into a spec", "spec this out", "write this up so someone else can build it" — or at the natural end of a `/grill-the-plan` session, when decisions have stabilised and need a durable, reviewable form. This is pure synthesis: NO new interviewing, only compaction of what the conversation and the codebase already established. Use even if the discussion feels too small to "deserve" a spec — a half-page spec that a reviewer can reject in one read is cheaper than a wrong implementation. Slash alias: /to-spec.
metadata	{"short-description":"Compact a settled conversation into a half-page reviewable spec (decisions, not transcripts)"}

To spec (compact a conversation into a reviewable spec)

What a spec is here

A spec is the smallest document a fresh session (human or agent) could pick up and build from without re-reading this conversation. It records decisions, not code. In this repo it must also survive the no-overclaim culture: a spec states what will be checked, never what will be "proven".

Workflow

1. Harvest, don't invent. Re-read the conversation and pull out every decision, constraint, and rejected alternative. If something essential was never decided, it goes in Open questions — do NOT quietly decide it yourself and do NOT reopen the interview (that is /grill-the-plan's job).
2. Ground it in the repo. Verify claimed facts against the actual codebase (does that module exist? which CI gate applies?). Use the repo's existing vocabulary — the same names the code and RESULTS.md already use.
3. Write these sections, in this order:
   • Goal — one paragraph, from the user's perspective: what changes for whom when this lands.
   • Non-goals — explicit exclusions. This section does the most work in review; a spec without non-goals invites scope creep.
   • Constraints — repo gates that apply (lint_claims, decontam, script-mode CI tests, ledger etiquette), box/GPU limits, ordering dependencies, anything a builder must not violate.
   • Acceptance checks — numbered, each an observable check: a command to run, a gate that must be green, a behavior to exercise. Phrase as "run X, observe Y", never "X should be correct". These become the verification plan for verification-recipe-runner at PR time.
   • Open questions — undecided items with an owner each ("needs user decision" / "needs codebase investigation"). An empty section must be earned, not assumed.
4. Keep decisions, drop coordinates. No file paths and no code snippets — they go stale before the spec is built. One exception: a snippet that IS the decision (a schema, a state shape, a config contract) may be inlined, trimmed to the decision-bearing lines and labelled as illustrative.
5. Size check. One to two screens. Longer means either scope is too big (send it to /to-tickets or /wayfinder) or you are writing implementation, not specification.
6. Present for review in the conversation, or write it where the user directs. If work will span sessions, note in the handover doc where the spec lives (see session-handover).

Quality bar

• A reviewer can disagree with the spec in one read — everything contestable is visible, nothing is buried in prose.
• Every acceptance check is executable by a session with no memory of this conversation.
• Nothing in the spec claims an outcome; it claims checks. "The gate passes" is a spec item; "the feature is correct" is not.

Do not

• Do not interview during synthesis — if the material is too thin to spec, say so and route back to /grill-the-plan instead of padding.
• Do not fill Open questions with your own guesses to make the spec look finished; an honest open question outranks a silent assumption.
• Do not include file paths, line numbers, or code except the single decision-encoding-snippet exception above.
• Do not promise results ("this will fix the flake") — promise checks ("acceptance check 3 exercises the previously-flaky path 20×").
• Do not merge Goal and Non-goals into one section; the boundary between them is the spec's main payload.

Method adapted from mattpocock/skills skills/productivity/to-spec/SKILL.md (MIT) — see THIRD_PARTY_NOTICES.md.