Spec Writing

Phase 4 makes the chosen bet buildable by someone who was not in the conversation, and measurable three months later.

Mode. Standalone writes the requested scope, numbered assertions and relevant states from the supplied requirements, current behavior and constraints, marking unknown facts and owner decisions; a draft authorizes no implementation. The lifecycle runs every step, writes 04-spec.md and gate 4. Both per operating modes. Step 5 calls the other design skills; a standalone spec loads only those it needs, tracking-standards for events. Two further modes, each with its own procedure and marker: synthesis, a spec from the conversation with no interview (synthesis, to-spec by name), and communication, release notes, updates, exec summaries and memos (product communication). Read the section of spec methods behind the step you are on.

Procedure

1. Read 03-solution-bet.md and 02-definition.md: the selected bet with its primary user action, the kill criteria, the success metric with its baseline; a spec with no chosen bet specifies a guess, so a missing bet stops the phase. Change track: phases 0 to 3 are covered by the mandate in 00-request.md, which is the bet; there is no phase 2 metric (step 7 runs only for a guardrail event), and a choice between solutions found while writing upgrades the work to feature (lifecycle-setup, the ratchet). Done when the bet, its primary action and the metric (or the mandate) are in front of you.
2. State what exists today in the area the bet touches, from the code where repo.read resolved, from the person otherwise. TECH.md, DOMAIN.md and the PRODUCT.md constraints bound the spec; contradicting one means naming it and why. Done when current behavior is written and every constraint that bounds it is named.
3. Write the impact on what exists (gate 4.11), one row each: existing data (shape, backfill or default, rows that break a new rule, counted with db.query where it resolved), contracts (APIs, webhooks, exports, integrations others consume), tracking events (each renamed or redefined event breaks dashboards and baselines), permissions (who sees the change), current users (default on or off, what moves, how they hear). "Nothing to do" with its reason counts; with nothing built yet, **Impact on what exists:** not applicable, {reason}; a change writes only the rows it touches, and current users. Done when every row it owes has a handling.
4. Bound the scope. In scope, then out of scope as not now, not ever by design, or not until X, including the boundary someone will argue with. A boundary a reasonable person could draw elsewhere is a pressure-testing round question with a recommendation; the rest you write. An undecided in-scope question goes under Not yet specified with who decides it and which criteria wait on it. On the change track write **Touches:**: what the change touches (interface, copy, data, personal data, permissions, money, messages, contracts, stack, or none of these), each explained in parentheses; it decides which of steps 5 to 11 apply (gate 4, Change track). Done when the out-of-scope list is non-empty (gate 4.2) and every contested boundary has the owner's answer.

5. Shape it with the person, in this order; each sub-step asks the person, and where this phase runs delegated the delegate returns the round and the main conversation asks it:

   1. Flows. ux-architecture writes information architecture, flows, per-step states, the component inventory and the accessibility floor into DESIGN.md; every flow traces to the phase 3 primary action. On the product track one flow is the first day, and the spec's **Activation:** names its criterion and event (gate 4.17).
   2. A real user, on a clickable prototype (product track, gate 4.13), before anything costly rests on the concept: ux-architecture (direction) builds one self-contained HTML file walking the primary flow with real words, and the person runs one session with someone from the ICP per spec methods, notes saved with scripts/bos.mjs evidence add --class interview --id P{n} under ## Real users with **Willingness to pay:** (4.14) and **Channel result:** (4.22) once the channel test returned. A concept that fails here goes back to phase 3.
   3. The domain. domain-model: entities, transitions with who and guard, invariants, awkward scenarios, rules put to the person, a logic prototype when the rules are non-trivial, the data sketch (gate 4.10).
   4. The agent (model output, gate 4.16). agent-design: autonomy per action, hand-off, injection surfaces with must-pass cases, degradation, the latency budget.
   5. The look. ux-architecture (direction) on the primary flow: reference screens, rendered versions, a choice in rounds (gate 4.9); the kit waits for the stack.
   6. The stack. system-design (stack): inherited layers read from the repository, a decision card per open layer, ADRs for the hard-to-reverse ones, TECH.md → Stack, the spec's ## Stack (gate 4.8); then back to ux-architecture (direction) for the kit.
   7. The system. system-design: components, contracts, external calls planned for failure, the scale defaults, the capacity, and a threat model whose mitigations are criteria (gates 4.18, 4.19).

   Done when DESIGN.md carries the flows, the domain model and the visual direction, the spec carries ## Stack, ## Architecture and ## Threat model, and on the product track ## Real users records a session that happened or the override with its reason.

6. Write the user stories, then the acceptance criteria. Numbered stories ("As a {actor}, I want {capability}, so that {benefit}") covering every actor and flow in scope. Then one criterion per requirement, numbered for phase 5, each tracing to a story: a subject that exists in the product, a verb with an observable outcome, and the condition under which it is checked (gate 4.1). Adjective test: strike every adjective; what remains is verifiable. Name the test seams: the highest points the behavior can be tested from, existing ones first, as few as possible, each with its criteria. Done when every story has a criterion and every criterion survives the adjective test and has a seam.
7. Enumerate states and edge cases. Six states per flow: empty, loading, partial, error, success, permission (gate 4.3 requires empty and error for every flow). Then edge cases: zero/one/many/too many, concurrency, interrupted, hostile input. Done when every case has an expected behavior, or a deliberate "undefined".
8. Write the quality bar (gate 4.12): permissions (who sees and does what; what someone outside the role gets), personal data (what is stored, who reads it, retention, deletion), performance (a budget with a number on the primary action, measured at gate 5.14), each as numbered criteria or "not applicable" with why. Accessibility, end-to-end, dependencies and secrets belong to the guardrail (gate 5.10). Done when all three areas are answered.
9. Design the tracking plan before the build (gate 4.4): work backwards from the phase 2 metric to the events and properties that compute it, check each against the catalogue via tracking-standards, new or existing. Done when the plan shows how its events produce the number.
10. Write the eval set when a criterion depends on model output, before the build and before the prompt: declare **Model output:** yes and write at least 20 cases (10 in lite mode) with a threshold, a judge and must-pass cases, including one per injection surface (gate 4.6); synthetic cases are labeled synthetic. Done when the dataset file exists, or the spec declares no model output.
11. List the constraint conflicts (gate 4.7): each requirement against the PRODUCT.md and TECH.md constraints, every collision with who decides it and the criteria it blocks, or the constraints checked and none colliding. Conflicts close with their owner before acceptance, or travel as blocking edges into phase 5. Done when ## Conflicts is written.
12. Write, gate and get it accepted. Write .builderos/initiatives/{initiative}/04-spec.md per the spec template, headings, bold labels and tables exact, and confirm DESIGN.md exists. Write ## What we chose in plain words, one row per choice as the template shows, opening with the rules that will surprise someone. Run gate 4. On a pass, present that summary first, then the spec, and ask for acceptance (a technical reviewer joins for a high-risk change); record it with the person's answer (scripts/bos.mjs record 4 --judged "{judge-id}=pass|fail,..." --accepted-by "who" where commands run). Done when gate 4 is recorded with the person's acceptance.

Watch for

More in spec methods.

Capabilities

Phase 4 needs no data capability. Without repo.read "what exists today" is thinner; the phase still runs.

Output Contract

## SPEC COMPLETE with the scope boundaries, the conflicts, the domain rules, the agent's behavior when a model acts, the stack, the architecture, the threat model and the visual direction with who chose them, the numbered acceptance criteria, the quality bar, the real-user session (product track), the state coverage, the tracking plan, the gate result and who accepted. The lifecycle artifact is 04-spec.md per the spec template; gate 4 parses its headings, bold labels and tables.