git:20261009.1da8791 to git:20261017.5b1062d

---

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-item

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.

Investigate observable questions first and research recorded history when rationale matters;

current code alone does not establish intent. Keep evidence, inference, and unresolved gaps

distinct. For each unknown, state the cheapest next action and blocking status or an explicit

reasoned deferral. Reversible implementation defaults stay within scope; human preferences,

authority, acceptance changes, consequential tradeoffs, and evidence-unsettled decisions go to

`grill-decisions` with evidence and a recommendation. Any small targeted experiment must fit

existing authorization and limits; no additional pilots, budgets, or outward actions are authorized.

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/<NNNN>-<slug>.md` and fill it in. The template carries

the section set, per-section authoring hints, and the lifecycle rules that apply after authoring.

Use `CONTEXT.md` vocabulary exactly for every concept it already names.

Describe concrete seams with independently verifiable outcomes: the behavior or interface delivered,

the verification boundary (what the check proves and leaves unproven), and interface prerequisites

or shared resources needed by each piece. File layout alone is not a reason to split or serialize

work. Keep initiative uncertainty in this design and execution state in Beads.

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`.

Create the tracking epic and link it back to the design doc:

```bash

bd create "<Design title>" --type epic --description "See .brain/designs/<NNNN>-<slug>.md" --spec-id design:<NNNN>-<slug>

```

`--spec-id` links the work 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`.

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

item-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.