MasterMind: Specify

The spec says what and why, for a reader who does not code. The how comes later, in blueprint. Read ~/.mastermind/engineering/core/spec-driven.md for the layout, IDs and lifecycle. Feature: $ARGUMENTS.

Write it

1. Open the folder. Pick the next number in specs/ and a two-to-four word name: specs/012-csv-export/. Revising an existing spec? Work in that folder instead. Search specs/ and the code for the concept first: a feature that already exists is amended, never specified twice.
2. Start from the template. specs/.templates/spec.md if present, else template.md.
3. Read what bounds it. specs/constitution.md, specs/product.md, the brief's glossary, and any earlier spec this one amends.
4. Write user stories in priority order. P1 alone is a usable product. Each story carries an independent test: how someone would see it working with no lower-priority story built. A story may rely on a higher-priority one; its test then assumes only those.
5. Write acceptance criteria with their trigger inside, numbered per story (US1/AC1), in the four shapes interview uses: When, While, If ... then, Where.
6. Write functional requirements (FR-001), each testable alone, and success criteria (SC-001), each measurable from the user's side with no technology named.
7. Fill the rest. Key entities (no fields or types yet), edge cases, out of scope, and assumptions.
8. Name things once. Add each new domain word to the glossary in .mastermind/brief.md, creating the file or the section if it is missing, and use those exact words in the spec.

Gaps: guess well, mark the few that matter

Fill a gap with the reasonable default for this kind of product and record it under Assumptions. Mark a gap [NEEDS CLARIFICATION: <question>] only when all three hold: it changes scope, security or the user's experience; two readings lead to different products; and no default is reasonable.

Three markers at most. Rank by scope, then security and privacy, then experience, then technical detail. Past three, the rest become assumptions. Then run interview on the spec to resolve them.

Check it before handing it on

Write checklists/requirements.md in the feature folder and test the spec against it:

• No technology, framework, library or API named anywhere
• Every requirement is testable and has one reading
• Every success criterion is measurable and names no technology
• Every story has an independent test and at least one acceptance criterion
• Edge cases, out of scope and assumptions are filled
• Every domain word matches the glossary in .mastermind/brief.md
• No more than three clarification markers remain

Fix what fails and re-check, at most three rounds. Anything still failing is listed in the checklist's notes and in your report. Set the status line to draft. Only interview sets clarified: a spec with no markers still gets its scan for the gaps nobody marked.

Gotchas

• Technology is a leak. "Use Postgres", "a React modal", "cache in Redis" decide the how before the plan exists. Replace each with the need it serves. The product's own surface is not technology: the commands a CLI user types, or the screens a user sees, belong in the spec.
• "Fast", "intuitive", "secure" are not requirements. Each needs a number or a named behavior.
• A story that cannot ship alone is a layer. "Set up the database" is a task, never a story.
• Do not invent the business. Who pays, legal limits, and pricing come from product.md, business.md or the user. Never from inference.
• One feature per folder. A title that joins two outcomes that ship separately is two features. Split it now. One capability with two parts, such as tagging notes and filtering by tag, is one.

Report

The folder, the stories with priorities, the checklist result, any marker still open, and the next step: interview, which runs its clarification pass on every spec.

Then run mastermind next and end with the step it names, so the user sees where the feature stands.