Writing Specs
Turn an intent into a requirements spec. Requirements are the what; leave the how (architecture, schemas, code) to design.
When to use
- You have a goal, brief, or feature request and need its detailed requirements before designing or building.
- Skip a trivial change whose single requirement is obvious: state it and go.
- If the intent itself is unclear, invoke
clarifying-intentfirst; this skill assumes what is wanted is roughly known. - If a reply has not directly closed a pending decision, invoke
clarifying-intent; this skill cannot turn that reply into approved requirements.
Step 1: Gather
- Pull the goal or brief, and read the relevant existing code. If a genuine
gap is left, invoke
clarifying-intent. Invent nothing you could have found.
Step 2: Write the requirements
Open assets/spec-template.md before you start. Fill a section only with
what this work has; the template says what an empty one carries.
Write each functional requirement as an observable behavior with a stable ID that no successor spec ever gives to a different requirement:
Right: R-07 rejects an expired token with a 401 Wrong: R-07 good authCarry each guardrail and obligation the template names, when it applies. Do not add a generic list of non-functional requirements.
Read
references/reference-forms.mdbefore choosing the first acceptance form. For each requirement, choose the cheapest form that can honestly judge it.If the form is an executable gate, write it as a proposed file beside the spec, never into the project; the implementer lands and runs it inside the task workspace as its
test-driven-developmentcheck. If the interface, or the authority to change the project, is still open, write the observable, the intended gate, its owner, and the handoff. Never invent an interface.List the edge cases and scenarios that break a naive build. Every sentence in the spec that states what the code does today (a command exists, a format carries a field) names the path and symbol it was checked against at the current revision. One that states what stored data holds (a column is never empty) names the smallest query over real rows that showed it, with its result and never the rows; cite no schema for it, since a schema says only what rows may hold. Rewrite one you cannot cite to what is known, or move it to open questions.
Step 3: Write and present
Fill the template's high-risk classification section, then write the spec to
.sdlc-skills/specs/{{YYYY-MM-DD}}-{{topic}}.mdor the user-set path. The spec is immutable: a change to it is a new spec in its own file (-{{n}}before.md) that names this one as its predecessor, never an edit.If any classification answer is off the ordinary route, or the user marks the work high-risk, dispatch the review in
assets/spec-review.mdbefore presenting, asdispatching-parallel-agentsStep 2 says, to a reviewer who is not the spec's sole author. That review blocks presenting the spec (Step 3.3). Record each finding's disposition, as the asset says. OnNEEDS_CONTEXT, supply the path it names and rerun once; a second is an open question for the decision owner.Present:
Spec {{absolute path}} — version {{identity (per template)}} Requirements: {{n}} Open questions: {{n}} Out of scope: {{n}} 1. Approve and hand off to design 2. Request changes 3. Reject 4. Cancel Recommendation: {{option the open-question state supports}} — {{one sentence}}.Ask this and end the turn;
clarifying-intentowns what closes it.REQUIRED SUB-SKILL: on option 1, invoke the next missing precondition:
ui-ux-design,system-architecture, ordata-modelwhen a non-trivial shape is still unresolved; otherwisewriting-plans. Never impose a phase that is already complete.
Gotchas
- A claim about the current code that reads as settled is planned as settled: a spec that said a sign-in command existed and a lock format carried a licence field reached implementation before anyone found that neither held on the base, each as a plan successor mid-task. Step 2.5 cites the path and symbol, or says it is unknown.
- A retired requirement ID reused for new work silently makes every earlier citation of it (test names, review comments, out-of-scope links) point at the new work.
- An executable gate written into the project while you are still specifying lands in whichever checkout is open, before any task workspace exists.