writing-specs

Writing specs

A spec is the contract: what's being built, what it must do, what it explicitly will not do, and how the pieces fit. It is what a plan implements against. It is not a plan — it does not enumerate steps, files, or commits.

When you're done

spec.md and spec.tracker.json exist in the initiative folder. Every section in the body is wrapped in <!-- section:N:start --> ... <!-- section:N:end --> flags with matching tracker entries. The user has approved the spec, and you've offered to invoke reviewing-specs.

Process

1. Read upstream — targeted only. Brainstorm (or roadmap row + parent roadmap thesis). Reference brainstorm content by section number (§2); every settled decision in the brainstorm should appear in the spec as a constraint or design choice. For roadmap-row context, read just the row's <!-- decision:N --> flag block plus the roadmap's ## Thesis section — not the whole roadmap. For sibling specs (collision awareness), read just their <!-- section:1 --> (Goal) and <!-- section:2 --> (Non-goals) flag blocks. Use Read offset/limit mechanically to land on flagged regions; cite them by flag in the spec body so the reference survives sibling-spec edits.
2. Lock the contract first. What does this ship? What does it not ship (out-of-scope is mandatory)? What are the success criteria? Get user approval on these three before drafting the body.
3. Draft sections one at a time. Show, get nod, move on. Required sections below.
4. Wrap each section in flags as you write. Ordinals are sequential within the spec.
5. Write spec.tracker.json (kind: "spec", populate sections, all status: "draft").
6. Self-review inline. Placeholder scan, contradiction scan, scope scan. Fix what you find. No re-review pass.
7. Hand off. Tell the user the path; offer reviewing-specs. Stop.

Required spec sections

You MUST scaffold the spec via dev-pipeline.js assess. Do not hand-write the structure; do not adapt a prior spec. The assess verb copies the canonical templates into the initiative folder and patches frontmatter from the brainstorm — the templates are the single source of truth for the six required sections, the section flag syntax, and the tracker schema. reviewing-specs and dev-pipeline.js validate pair body flags ↔ tracker entries by ordinal, and a hand-written spec that drifts will fail validation.

node greymatter/scripts/dev-pipeline.js assess <init>/brainstorm.md --to spec

This writes <init>/spec.md (with topic patched into frontmatter) and <init>/spec.tracker.json (kind: "spec", sections at status: "draft"). Then populate. The body template ships all six required sections (Goal, Non-goals, Design, Constraints, Rejected alternatives, Open threads) wrapped in section:N flags with placeholder content. The tracker template ships kind: "spec" with the matching six sections at status: "draft".

You MAY add sections beyond the six when the topic genuinely needs them (e.g., migration, security, rollout). When you do, you MUST wrap each in a section:N flag AND add a corresponding tracker entry in the same change. You MUST NOT remove or reorder the six required sections.

Targeted reads

When the spec references existing code (constraints section, design section), cite by symbol whenever the code has a name — lib/auth/token.js::verifyToken. The symbol name is the stable handle: greymatter's get_node_bundle <project> lib/auth/token.js verifyToken resolves it without caring what line it lives on, so the reference survives any future edit to the file. Line ranges (lib/auth/token.js:L42-L78) are the fallback for unnamed regions only — file headers, imports, config blocks. A spec that says "see lib/auth/token.js" without a symbol or range pushes the work of finding the relevant code onto every downstream reader and accumulates edit-debt every time the file changes.

Anti-patterns

• Steps in the spec. "Then we'll add a function that…" belongs in the plan. The spec describes what, not how to build it.
• Empty non-goals. "Out of scope: TBD" is a spec failure. Name three things you're not building.
• No rejected alternatives. Forces nothing; future readers can't tell why this path won.
• Editing the body for status. Status lives in spec.tracker.json. Body edits are content corrections only — and content corrections that change the contract should write a superseding spec, not mutate this one.