to-design git:20261017.5b1062dA

Immutable. This exact content never changes and is served at /api/v1/blob/08aba9a1afcc2f96.

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

The doc is born `lifecycle: draft`; flip it to `active` in step 5, once the epic exists.

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

### 4. Settle scope and execution authority

Agree scope, success criteria, acceptance and UAT with the human before unattended work. Name
the UAT journeys, environment, required evidence, and gaps; agents may run agreed UAT. Missing
evidence is a gap, never an assumed pass or an automatic demand for human testing.

Record the approved execution contract in the design or linked handoff record: scope, delivery
branch/base, required checks and UAT, review expectations, provider/auth and agent identity,
PR authority, finite worker cap and whole-loop/retry limits. Record the human's approval and any
narrower overrides. Availability of credentials or tools does not establish authorization.
If execution authority is not yet requested, mark it unapproved; authoring and decomposition may
finish, but execution waits. An execution request alone does not approve a proposed contract.
Resolve foreseeable consequential decisions through `grill-decisions` with evidence and a
recommendation. New scope, authority, or criteria decisions stop affected work, preserving criteria.

Completion: design scope and acceptance are agreed; execution authority is either recorded as
approved or explicitly missing. A complete applicable contract is reusable without repeat `GO`.

### 5. Create the epic bead

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

### 6. 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
  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.