Writing the spec
Find the spec and read its own contract first, every time. It wins over anything
here.
git ls-files | grep -iE '(^|/)(spec|specs|requirements)(/|$)' | head
A spec root usually holds a README.md stating the rules for the rest, an index,
and one folder per domain. If the project has no spec, do not invent one inside a
ticket: say so, and propose the root as its own change.
What belongs here
The spec says what the product does and why. Architecture says how the
code is shaped. The test: a sentence that survives a full rewrite of the
implementation belongs in the spec. A sentence naming a crate, a file, a
framework, a wire format or a schema does not.
That line is the one reviewers enforce hardest, because a spec that leaks
implementation stops being reviewable by the people who care what the product
does.
Before writing
Find the space. One folder per domain, using the nouns the project's architecture
already uses. A new space needs a reason, not a new noun for an existing domain.
Read the space's own README and its sibling chapters before adding to them. Two
chapters that disagree on the same rule is the worst defect a spec can carry,
because both readers think they are right.
Every section carries a status
A reader has to know whether a sentence describes today or an intention. Use the
project's vocabulary if it has one. Where it does not, this set covers it:
SHIPPED, AGREED, DRAFT, DESIGN, NOT IMPLEMENTED
A section without a status is a bug in the spec. DESIGN, NOT IMPLEMENTED must
say why it was deferred and what shipped instead. That record is worth more than
the design was.
Requirement IDs
Every normative statement, anything a reader could implement or test, carries an
ID and its own status:
LIB-4 (AGREED) - A rescan never deletes user data. A file that disappears is
marked absent; its watch history survives.
- One prefix per space, one space per prefix. Pick something legible and stay with it.
N is assigned once. Never renumbered, never reused. A deleted requirement
retires its number, so a link in an old ticket never silently points at a
different rule.- One ID is one testable idea. A line hiding two requirements needs two IDs.
Take the next number from the project's generated index if it has one, or from
git log if it does not. Never by counting the prose in front of you: a retired
number is invisible there, and reusing it corrupts every link that pointed at the
old rule.
Sizing
A requirement maps to one story; a domain maps to one epic. A requirement that is
really five stories wearing one ID is what makes a spec useless for planning.
Split it.
The other direction is also wrong: an ID on a sentence nobody could test is
noise. If you cannot say how a reader would prove it true, it is prose, not a
requirement, and it needs no ID.
Prose
A tired reader on a phone follows it on the first read. Paragraphs under five
lines, one idea per sentence, no undefined jargon, no passive construction hiding
who acts. A spec that is correct and unreadable is a defect.
Run the unslop skill over anything before committing it, and the
ticket-writing skill when the requirement becomes work.
Before the PR
Where the spec ships an index or a checker, regenerate and run it, then commit
whatever it wrote. Look for the scripts in the project's manifest; they usually
fail on a stale index, a duplicate ID, a mixed prefix or a missing status.
Generated artefacts are never hand-edited.
The spec changes only through a pull request, and a PR that changes behaviour
changes the spec in the same PR. For anything large or contested, write the design
document the project uses for that (an RFC or an ADR) first, and let the spec
record the outcome rather than the argument.
Where the project ships a spec review agent, write for that review and run it
before asking for a human one.