Write Spec
Goal
Write a spec: the decisions that only I can make, and a definition of done that a fresh
session can build from and that the verify-spec skill can check.
Quick start
Do the sections in order. First read my request against the code:
git rev-parse --show-toplevel && git status --short --branch
ls specs 2>/dev/null
git check-ignore -q specs/x || echo 'specs/' >> "$(git rev-parse --git-path info/exclude)"
- DO run the third command; it adds
specs/ to the ignore list of this clone only, in a
file that git does not track, so that the open-pr skill never commits or pushes a spec
- DO read the code that the request touches before the first question; a question that the
repository answers costs me a turn
- DO find a file that already does a similar thing; it becomes the reference in the spec,
because source code shows a pattern better than my words do
How to find the unknowns
Before the interview, show me the unknowns in a message: the decisions that this work forces
and that my request does not make, with the ones that I probably do not know about. End the
turn with one question in text: what I decided already, and what in the list is new to me.
Decision | Why it matters | Recommendation
- DO explain each term that I did not use in my request
- DO include what the code makes necessary and I did not mention, such as a migration of
saved data, a second platform, or a screen with no data
- DO NOT list a choice of implementation that you can change later at no cost to me; that
choice is yours
- DO NOT open the question tool in the turn of the list; its dialog hides the list, and I
must read the list before I answer a question
How to interview me
Ask in this order, because an early answer changes the later questions:
1. What changes the data model, an interface between two parts, or what the user sees
2. What is out of scope, and how complete the result must be
3. The edge cases, and what must occur in each one
4. How to verify that the work is done
- DO ask one question at a time with the
AskUserQuestion tool, or in text when the
session does not have it, with two to four choices and your recommendation first; give
each choice the strongest reason to pick it, and not a reason against it
- DO ask about a decision only when a different answer changes the result for me, and
skip a topic of the list that the code settles; give each other decision a default, and
write that default in the spec as assumed
- DO offer a prototype with fake data, or three or four different directions, when I
cannot describe the result but I would know it when I see it; put it in
specs/<topic>/,
which git ignores, because the open-pr skill commits each other file that it finds
- DO name the direction that I pick under Constraints as a reference; the build and the
verify-spec reviewer read it, and it shows more than my words do
- DO NOT ask me how to build it; I decide what the result is, and you decide the path
How to write the spec
# <Feature>
Status: draft
## Goal
The problem, the result, and who or what it affects.
## Decisions
- <What I decided, with the choice that I am most likely to change first>
- <A default that I did not confirm> (assumed)
## Requirements
1. <A behaviour that a person or a test can observe>
## Edge cases
Each one needs a test.
- <Case>: <what must occur>
## Out of scope
- <What this work does not do>
## Constraints
- Reference: <a file that already does a similar thing>
- <A library, a pattern, or a behaviour that must not change>
## Check
- <Command>: <the output that means pass>
- <Action in the running app>: <what to see>
## Deviations
- DO write to
specs/<topic>.md, with the topic in two to four words of kebab case, or to
the path that I give; one file for each piece of work keeps two specs apart
- DO write each requirement as a behaviour that a person or a test can observe, not as a
step of the implementation; a spec that fixes the path stops a better path that you find
during the build
- DO number each requirement; the
verify-spec skill reports by number
- DO make each line under Check exact: a command with the output that means pass, or an
action in the running app with what to see; leave the action out when the project has no app
to run, and give no number of tests, because the
verify-spec skill finds the test for each
edge case
- DO say how complete the result must be, such as the empty state and the error state; a
request with no stated scope gets the smallest result that satisfies it
- DO keep the spec in proportion to the work, and on one page when the work permits; write
an edge case only when its result does not follow from a requirement, and an assumed default
only when a different default changes the result
- DO leave Deviations empty; the build writes there each place where it left the spec
How to hand off
Show me the decisions in a message, with the assumed ones marked, and end the turn; I answer
in text. Correct the spec until I accept it, then set its status to accepted, keep each
(assumed) mark, and give me this prompt for a fresh session:
Build specs/<topic>.md. When the code forces you to leave the spec, pick the conservative
option, write it under Deviations in the spec, and keep going. When the build is done, use
the verify-spec skill.
- DO ask me each question that is still open before you set the status; a spec with an
open question is not a definition of done
- DO NOT start the build in this session, unless I ask for it; a fresh session starts with
a clean context and the written definition of done, without the turns of the interview
Copyright © 2026 Lorenzo Mazzarotto
1---2name: write-spec3description: Finds the decisions that a feature or a change leaves open, interviews the user about them, and writes a spec with requirements that can be checked. Use when asked to write a spec, or to specify, scope, or think through work before it is built, or when a request for large work leaves its main decisions open. Not for a change that one prompt describes in full.4metadata:5 source: https://skillmd.com/skills/mazzsva/write-spec6---78# Write Spec910## Goal1112Write a spec: the decisions that only I can make, and a definition of done that a fresh13session can build from and that the `verify-spec` skill can check.1415## Quick start1617Do the sections in order. First read my request against the code:1819```bash20git rev-parse --show-toplevel && git status --short --branch21ls specs 2>/dev/null22git check-ignore -q specs/x || echo 'specs/' >> "$(git rev-parse --git-path info/exclude)"23```2425* **DO** run the third command; it adds `specs/` to the ignore list of this clone only, in a26 file that git does not track, so that the `open-pr` skill never commits or pushes a spec27* **DO** read the code that the request touches before the first question; a question that the28 repository answers costs me a turn29* **DO** find a file that already does a similar thing; it becomes the reference in the spec,30 because source code shows a pattern better than my words do3132## How to find the unknowns3334Before the interview, show me the unknowns in a message: the decisions that this work forces35and that my request does not make, with the ones that I probably do not know about. End the36turn with one question in text: what I decided already, and what in the list is new to me.3738```text39Decision | Why it matters | Recommendation40```4142* **DO** explain each term that I did not use in my request43* **DO** include what the code makes necessary and I did not mention, such as a migration of44 saved data, a second platform, or a screen with no data45* **DO NOT** list a choice of implementation that you can change later at no cost to me; that46 choice is yours47* **DO NOT** open the question tool in the turn of the list; its dialog hides the list, and I48 must read the list before I answer a question4950## How to interview me5152Ask in this order, because an early answer changes the later questions:5354```text551. What changes the data model, an interface between two parts, or what the user sees562. What is out of scope, and how complete the result must be573. The edge cases, and what must occur in each one584. How to verify that the work is done59```6061* **DO** ask one question at a time with the `AskUserQuestion` tool, or in text when the62 session does not have it, with two to four choices and your recommendation first; give63 each choice the strongest reason to pick it, and not a reason against it64* **DO** ask about a decision only when a different answer changes the result for me, and65 skip a topic of the list that the code settles; give each other decision a default, and66 write that default in the spec as assumed67* **DO** offer a prototype with fake data, or three or four different directions, when I68 cannot describe the result but I would know it when I see it; put it in `specs/<topic>/`,69 which git ignores, because the `open-pr` skill commits each other file that it finds70* **DO** name the direction that I pick under Constraints as a reference; the build and the71 `verify-spec` reviewer read it, and it shows more than my words do72* **DO NOT** ask me how to build it; I decide what the result is, and you decide the path7374## How to write the spec7576```markdown77# <Feature>7879Status: draft8081## Goal82The problem, the result, and who or what it affects.8384## Decisions85- <What I decided, with the choice that I am most likely to change first>86- <A default that I did not confirm> (assumed)8788## Requirements891. <A behaviour that a person or a test can observe>9091## Edge cases92Each one needs a test.93- <Case>: <what must occur>9495## Out of scope96- <What this work does not do>9798## Constraints99- Reference: <a file that already does a similar thing>100- <A library, a pattern, or a behaviour that must not change>101102## Check103- <Command>: <the output that means pass>104- <Action in the running app>: <what to see>105106## Deviations107```108109* **DO** write to `specs/<topic>.md`, with the topic in two to four words of kebab case, or to110 the path that I give; one file for each piece of work keeps two specs apart111* **DO** write each requirement as a behaviour that a person or a test can observe, not as a112 step of the implementation; a spec that fixes the path stops a better path that you find113 during the build114* **DO** number each requirement; the `verify-spec` skill reports by number115* **DO** make each line under Check exact: a command with the output that means pass, or an116 action in the running app with what to see; leave the action out when the project has no app117 to run, and give no number of tests, because the `verify-spec` skill finds the test for each118 edge case119* **DO** say how complete the result must be, such as the empty state and the error state; a120 request with no stated scope gets the smallest result that satisfies it121* **DO** keep the spec in proportion to the work, and on one page when the work permits; write122 an edge case only when its result does not follow from a requirement, and an assumed default123 only when a different default changes the result124* **DO** leave Deviations empty; the build writes there each place where it left the spec125126## How to hand off127128Show me the decisions in a message, with the assumed ones marked, and end the turn; I answer129in text. Correct the spec until I accept it, then set its status to `accepted`, keep each130`(assumed)` mark, and give me this prompt for a fresh session:131132```text133Build specs/<topic>.md. When the code forces you to leave the spec, pick the conservative134option, write it under Deviations in the spec, and keep going. When the build is done, use135the verify-spec skill.136```137138* **DO** ask me each question that is still open before you set the status; a spec with an139 open question is not a definition of done140* **DO NOT** start the build in this session, unless I ask for it; a fresh session starts with141 a clean context and the written definition of done, without the turns of the interview142143Copyright © 2026 Lorenzo Mazzarotto