--- name: to-design description: Formalizes a multi-step initiative as a design doc in the Brain plus a tracking epic bead. Use when an initiative is multi-step, crosses modules, or carries meaningful unknowns — before it is decomposed into work items — or when arriving from grill-decisions or find-unknowns with a shape worth writing down. --- # To Design Synthesize the current conversation context and codebase understanding into a design doc under `.brain/designs/`, then open the epic that tracks it. `DOTBRAIN.md` governs the doc over its whole life; this skill covers authoring it. ## Stop before you start A design doc earns its keep only when the initiative is multi-step, crosses modules or workflows, needs explicit scope boundaries, or carries meaningful unknowns. Small, obvious, single-slice changes go straight into beads instead. If the initiative warrants an ADR, stop and run `grill-decisions` first. ADRs own durable decision rationale; this doc owns the initiative's design, unknowns, and rollout. State the one-sentence reason this needs a doc rather than a bead before creating anything. ## Process ### 1. Read the local operating context Read the nearest `AGENTS.md`, `CONTEXT.md`, and the ADRs and design docs relevant to the initiative. If `.brain/docs/` holds runbooks or reference notes bearing on the work, read those too. Completion: every concept this initiative touches is paired with the project's existing term or flagged as needing a new one, and every ADR it interacts with is listed. ### 2. Surface the unknowns before writing Territory you have not inspected produces designs that break on contact. For unfamiliar codebases or broad changes, run `find-unknowns` — it is the blind-spot pass, and its output seeds `Known Unknowns` directly. Where the area is already familiar, inspect the relevant modules yourself and produce a short module sketch for the user: touched modules or systems, likely integration points, obvious constraints, open questions. Confirm the sketch with the user before creating anything. Completion: every module the initiative touches is either inspected or listed as a known unknown, and the user has confirmed the sketch. ### 3. Write the design doc Design docs use the same sequential naming as ADRs: scan `.brain/designs/` for the highest existing `NNNN-` prefix and increment by one (`0001` if none exist yet). Copy `templates/design.md` to `.brain/designs/-.md` and fill it in. The template carries the section set, per-section authoring hints, and the lifecycle rules that apply after authoring. The doc is born `lifecycle: draft`; flip it to `active` in step 4, once the epic exists. Use `CONTEXT.md` vocabulary exactly for every concept it already names. Completion: every section you kept is filled, every section you dropped is deleted along with its hints, and each goal has a matching entry under `Success Criteria`. ### 4. Create the epic bead Create the tracking epic and link it back to the design doc: ```bash bd create "" --type epic --description "See .brain/designs/-.md" --spec-id design:- ``` `--spec-id` links the execution graph back to the design doc. The epic stays private even when the project configures a public tracker; attach `--external-ref` only when this initiative was promoted from an already-existing public collaboration issue. Set the doc's frontmatter to `lifecycle: active`. Completion: the epic exists, its `--spec-id` matches the doc slug, and the doc reads `lifecycle: active`. ### 5. Hand off Summarize what was created: the design doc path and the epic bead ID. Recommend `to-issues` as the next step. ## What goes where Three artifacts hold different material, and the design doc holds only the middle one: - **Beads** hold execution: ready, blocked, done, dependencies, claims, acceptance, and slice-local implementation facts. - **The design doc** holds the initiative's design story: shape and interfaces, verification criteria, unknowns, deviations, rollout. - **ADRs** hold durable, cross-cutting, expensive-to-reverse decisions and their rationale. Link them from the design doc; state the rationale once, in the ADR.