| name | spec-writing |
| description | Write a technical or feature specification covering behavior, states, edge cases, and acceptance criteria. Use whenever the user mentions spec, feature spec, technical spec, behavior spec, or needs a document that an engineer can implement against. |
spec-writing
a spec answers "how will this behave in every situation it could be in?" without describing implementation.
the difference from a prd
a prd says why and what. a spec says how it behaves. the prd answers "should we build it?". the spec answers "what exactly are we building?".
structure
# [feature name] spec
## overview
one paragraph: what this is, who uses it, what it lets them do.
## user-facing behavior
### entry points
how do users get here. list every path.
### primary flow
step by step, what the user does and what the system does back.
### states
- default
- loading
- empty
- partial (some data present, some missing)
- error
- success
- offline
for each, describe: what's shown, what's interactive, what changes when state changes.
### edge cases
list them explicitly:
- input outside expected range
- network failure mid-action
- concurrent edits
- expired auth
- permission boundaries
- very large inputs
- very small or zero inputs
- characters outside ascii
- timezone considerations
## data
### inputs
each field: name, type, validation, source.
### outputs
each piece of data the system produces or stores.
### persistence
what gets saved, where, for how long.
## permissions
who can see what.
who can do what.
how permission changes propagate.
## acceptance criteria
given/when/then statements that pass when the feature is correctly built:
given [precondition]
when [action]
then [expected result]
write enough of these to cover every state and every edge case.
## out of scope
explicit list of things adjacent that this spec does not address.
## open questions
what's not decided yet and who decides.
rules
- specs are not implementation. don't dictate database choice or framework. do dictate behavior the user experiences.
- every behavior gets an acceptance criterion. if you can't write one, the behavior isn't specified.
- be boring. specs are read by people who need to implement, not be entertained.
