To-Spec
Convert ONE well-understood change into a precise, implementation-ready spec.
Not for vague multi-direction initiatives (use wayfinder) and not for breaking
work into many tasks (that is to-tickets).
When To Use
- "Write a spec for X", "spec this out", "make it concrete"
- A bug diagnosis produced a fix that needs requirements agreement first
- A feature was discussed in chat and must survive context loss
- Before
buildon a SPEC-driven repo
If the repo already has SPEC.md governed by the spec skill, AMEND it through
that skill's format instead of creating a competing document. This skill drafts;
the spec skill owns the file.
Request template
Optional, but it front-loads the answers step 1 would otherwise have to ask for.
Write a spec for this change.
Change: <the one feature, fix, or change>
Problem: <what is wrong or missing, and for whom>
Outcome: <observable behavior once done>
Out of scope: <what this deliberately does not cover>
Constraints: <compatibility, performance, deadlines, must-not-breaks>
Repo state: <existing SPEC.md governed by the spec skill? yes/no>
Follow the to-spec skill. Ask me only what you cannot determine from the repo.
If a SPEC.md already exists under the spec skill, amend through that skill
rather than creating a competing document.
Workflow
1. Clarify Intent
Answer before writing:
- Problem: what is wrong or missing, for whom
- Outcome: observable behavior after the change
- Scope boundary: explicitly what is OUT of scope
- Constraints: stack, perf, security, compat, deadlines
Ask the user only what cannot be inferred from code. Never invent requirements.
2. Ground In The Codebase
Inspect relevant files first; a spec disconnected from real code is fiction.
- Where does the change land (files/modules)?
- What existing patterns/conventions must it follow?
- What tests exist that will constrain behavior?
- What breaks if we do nothing?
3. Write The Spec
Use this shape (adapt headings to repo conventions):
# Spec: <Title>
Date / Author / Status: DRAFT | REVIEW | APPROVED
## Problem
<1-3 sentences with evidence.>
## Goal
<Observable end state, testable.>
## Non-Goals
- Explicitly excluded item
- ...
## Design
<Approach at the level a reviewer can evaluate: data flow, API surface,
modules touched, key tradeoffs considered and rejected.>
## Invariants
- V1: <property that must always hold>
- V2: ...
## Tasks
- T1: <concrete unit of work> — files: <paths>
- T2: ...
## Verification
| Check | How |
|---|---|
| Unit/functional tests | <commands> |
| Manual verification | <steps> |
## Risks
- <risk>: <mitigation>
Rules: every task names files; every goal maps to a verification row; invariants are testable statements, not vibes.
4. Review Loop
- Present the spec summary (problem, goal, non-goals, task count).
- Ask for objections on scope and design, not wording.
- Incorporate feedback; bump status DRAFT -> REVIEW -> APPROVED.
Do not start implementing from a DRAFT spec unless the user says so.
5. Hand Off
| Situation | Next |
|---|---|
| Approved, single-session work | implement directly (build if repo uses SPEC.md) |
| Many tasks across sessions | to-tickets |
| Big plan should be shareable | render via postplan-upload |
| Discovered mid-spec it is actually vague | stop, escalate to wayfinder |
Guardrails
- No implementation code while drafting the spec.
- Do not pad: if it fits in a paragraph, the answer is a paragraph, not a spec.
- Keep specs dated and status-marked; stale unmarked specs are dangerous.
- Secrets never go into specs (endpoints yes, keys no).
Related Skills
spec- owner of repo-root SPEC.md format (amend via it)build- executes SPEC-driven tasks with backprop on failurecheck- audits drift between SPEC.md and codeto-tickets- split approved spec into trackable ticketsbug-diagnosis- upstream source of fix specs