yass — Brainstorming a Spec

How an agent turns a user’s request into a spec set that another agent can implement cold. The keywords below bind the agent running this flow, in the RFC 2119 sense.

Why the dialogue exists

The spec set is the only thing the implementing agent will hold: not this conversation, not this document. Every behavior the spec leaves unstated, that agent decides alone, and two agents decide differently. Each question below moves one such decision to the user while it is still cheap.

Gate

• MUST-NOT write product code, scaffold, install a dependency, or create a project before the user approves the spec set.
• MUST-NOT write a spec file before the user confirms the written-back understanding (stage 2). WHEN the work is a retrofit, the code pins the intent: the draft is the write-back and stage 5 is its review.
• Each gate takes its own yes, whatever the size of the request.
• Skip a question only when the request or the repository already answers it — never because the answer seems obvious.
• WHEN no user can answer: MUST-NOT pass a gate; report the open questions and stop.
• MAY read the repository and run yass commands at any stage.

Stage 1 — Classify, out loud

State the class in one sentence before the first question, so the user can override it.

• Fresh project: yass reports project none. The root spec comes first, then the specs it reaches.
• Feature: a root governs the directory. MUST read yass list, locate what the feature touches with yass find and yass refs, and yass query only those documents; MUST-NOT read spec files by hand for what those commands serve. New behavior extends existing specs before it adds new ones.
• Several independent subsystems in one request: decompose first — name the pieces, their order, and the boundaries between them — then run this flow once per piece.
• Either of the first two is also a retrofit when the code already exists and the spec is written after it. Then the code is the interviewee: MUST answer stages 2 and 3 from it, and ask the user only where it is ambiguous, self-contradictory, silent, or looks accidental — and then whether the spec pins that behavior or corrects it.

When in doubt whether a request is several subsystems, decompose. Complexity found mid-flow means stop and decompose then; nothing shrinks a class once taken.

Stage 2 — Establish intent

• MUST know, before proposing anything: what the thing is for, who or what uses it, and what “done” observably looks like.
• MUST put one decision per message to the user, and batch what the request or the repository already answers as proposed defaults for them to correct. SHOULD offer choices with a recommended default marked, so the user corrects rather than composes; WHEN the choice shapes the spec — a wire format, a storage model, a dispatch structure — MUST present two or three options and their trade-offs.
• MUST then write the understanding back in a few lines, separating what the user said from what was assumed.

Stage 3 — Round the edges

• MUST read yass docs guidance first: it owns the edge cases this stage asks about, and this document does not restate them. Section names below are its.
• Interview by slot, for each spec the set will hold: propose every answer with a marked default and let the user correct in one reply, one slot per message where the user must decide and batched where the request, the repository, or the code already answers. Every answer becomes an obligation.
  • INPUT — the forms accepted; for a closed set, the out-of-set and missing cases; for split input, every boundary (Case coverage).
  • RETURN — what is yielded, in its exact shape: format, ordering, numbering, and what an empty result looks like.
  • ERROR — each foreseeable failure with its observable outcome, then the residual or the exhaustiveness that replaces it (Case coverage).
  • SIDE-EFFECT — what changes outside the return, and what MUST-NOT change.
  • INVARIANT — only what fits none of the above.
  • Boundaries — WHEN one spec consumes what another produces: what is trusted, what is re-checked, and what happens on violation (Composition, Case coverage).
  • Constraints that are not behavior — stack, algorithm, startup order: a design: block bound with USES (The root file).

Stage 4 — Draft

• MUST lay files out as guidance’s Granularity, The root file, and Ordering say; yass docs reference settles a construct in doubt.
• MUST write only obligations: nothing from the conversation survives except inside a design: block something USES.
• MUST run yass validate and yass lint and fix every finding before showing a draft.

Stage 5 — Review

• MUST put every spec document in front of the user and ask whether it is right: in chat, a short file whole and a long one spec by spec; or, WHEN the set is large or the work lives on a branch, as a pushed diff reviewed there.
• Before showing, MUST apply guidance’s Case coverage pass and its Implementer view rehearsal to the draft and check what the tools cannot: an obligation with two readings, two that contradict. Fix, then show.
• The user’s corrections go back into the files. Re-run validate and lint after each.

Stage 6 — Hand off

• WHEN the user approves the spec set: report where the root is and, WHEN there is code to write, how to begin — an implementing agent starts fresh in the project directory, runs yass, and builds what the spec set describes — then MUST stop.
• Before handing off, MUST re-apply guidance’s Implementer view rehearsal to the approved set and fix and re-show whatever it surfaces.
• Implementing here is a new request. WHEN the user makes it: MUST work from the spec set through yass query, not from memory of this conversation — a gap that surfaces there is a spec defect to fix, not a gap to fill silently.

Red flags