# Brainstorm Sections

This reference describes what makes a great requirements-only unified plan
artifact produced by `spec-brainstorm`.
It does NOT prescribe how the doc looks on the page — rendering is handled by
the format-specific references (`markdown-rendering.md`, `html-rendering.md`).

## The outcome

A great brainstorm produces the first version of the same plan artifact that
`spec-plan` later enriches. It enables three audiences to act:

- **The planning agent** (`spec-plan` or a human) produces an implementation
  plan without inventing user behavior, scope boundaries, or success
  criteria — the brainstorm answered those.
- **The reviewer** sees the framing choices, distinguishes pinned from open,
  and catches scope gaps before planning.
- **The future reader** traces why the proposed thing matters, who it's for,
  and what success looks like.

Sections earn their place by serving one of these audiences. Omit padding.

## Unified plan skeleton contract

New `spec-brainstorm` outputs live under `docs/plans/` and use the unified plan
artifact contract:

- **Path:** `docs/plans/YYYY-MM-DD-NNN-<type>-<topic>-plan.<md|html>`.
- **`artifact_contract: spec-unified-plan/v1`**.
- **`artifact_readiness: requirements-only`**.
- **`product_contract_source: spec-brainstorm`**.
- **`execution`** only when the brainstorm has enough signal to classify the
  eventual execution domain. For software features, use `execution: code`.
  For non-code deliverables, follow the universal-brainstorming route instead
  of pretending the artifact is executable code.
- **`status: active`** for a Markdown software unified plan. HTML output and
  the universal-brainstorming route do not carry lifecycle metadata.

A requirements-only unified plan is kept **light and standalone-readable**. It
includes:

- `## Goal Capsule` with objective, product authority, and open blockers.
- `## Product Contract` containing the brainstorm sections below.

Do **not** emit a `## Goal Launch Block` or `## Reader Index`: the launch prompt
is skill-emitted at handoff, not a doc section, and the contract carries no
Reader Index — consumers wayfind by scanning headings. It also omits empty
`Planning Contract`, `Implementation Units`, `Verification Contract`, and
`Definition of Done` sections — empty placeholders make requirements-only docs
look executable and waste downstream tokens. `spec-plan` adds those sections when
it enriches the same file in place. The next step (planning) is conveyed by the
Phase 4 handoff menu, not by a section in the doc.

Historical `docs/brainstorms/*-requirements.*` files remain valid legacy
inputs. Do not migrate or rewrite them when creating new artifacts.

## Decide whether a doc is warranted at all

Brainstorm dialogue does not always need to produce a durable document.
Skip document creation when **both** hold:

- The user only needs brief alignment — no exploration produced novel scope,
  framing, or decisions worth preserving in IDed shape.
- Any durable decisions made during the dialogue can flow naturally to
  downstream artifacts (`spec-plan`, the commit message, `docs/solutions/`)
  without a brainstorm doc as an intermediary.

The trigger for creating a doc is when the dialogue surfaced enough
structural decisions, scope boundaries, or acceptance criteria that
downstream consumers (planner, reviewer, future reader) need them in a
durable, IDed form — not just as conversational artifacts.

**Stress test:** a brainstorm about a tiny bug fix where the user asks "fix
this with a null check or with upstream validation?" and the agent confirms
"upstream validation, here's why" doesn't need a brainstorm doc. The
decision flows to `spec-plan` (or directly to commit message, or to
`docs/solutions/` if it's a pattern worth carrying) without a brainstorm
artifact in the middle.

Conversely, a brainstorm about a multi-actor feature with contested scope
and several behavioral conditions probably does need a doc — the planning
agent needs the structured content the dialogue produced.

## Match depth to content

When a doc IS warranted, depth matches what the dialogue produced. A
brainstorm with sparse content produces a sparse doc; one with rich content
produces a rich doc. Don't add ceremony to make a slim brainstorm look
substantial.

## Prose economy

Match-depth-to-content sizes *which* sections appear and how deep each goes.
This sizes *how the kept prose reads*. A section can be material and still be
written loosely — the failure mode is a material section padded into a wall of
text where contradictions hide and a downstream agent loses the thread. Length
that earns its place is fine; wordiness around that length is not.

Hold every kept section to these:

- **Lead with the decision or outcome.** Put the conclusion first, then the
  reason, then background; keep one claim plus its support per paragraph. Don't
  bury the chosen scope, an open blocker, or a Key Decision beneath its
  rationale. This does not override section roles — Summary stays proposal-only,
  Problem Frame stays motivation-only and never restates the remedy.
- **One idea per sentence.** A Summary is a handful of sentences, not one
  sentence with five semicolons and four parentheticals. If a sentence needs a
  second parenthetical to stay true, split it.
- **A requirement is one sentence of intent plus at most one qualifier.** When
  a requirement would specify two outcomes ("either A or B, planning decides"),
  state the intent and send the fork to Outstanding Questions — don't write both
  arms in full inside the requirement.
- **Cut hedges and intensifiers.** "Critically", "deliberately", "explicitly",
  "genuinely", "actually", "simply" carry nothing a downstream agent acts on.
- **Prefer the verb to the nominalization.** "Demote the grid", not "the
  demotion of the grid is the deliberate change in this brief".

Precision is not padding: keep IDs, dates, actor names, domain terms,
conditionals, and exact thresholds verbatim; when a concrete anchor is knowable
from the work already done, use it instead of a vague abstraction. Economy
targets the connective tissue around precision, never the precision itself.

**Resolve in place; don't stratify.** When a later decision answers a parked
question or supersedes earlier text, rewrite or remove the original entry —
don't append a separate "resolutions" layer that leaves the superseded text
standing, and don't keep superseded prose as strikethrough. Version control
holds the history. Stacked question/resolution strata double the reading surface
and hide which text is live.

**Named test, run before the doc is declared written:** could a reader find a
contradiction in each section in one pass? A sentence carrying more than one
parenthetical, or a requirement specifying two outcomes, fails the test — split
it or defer it.

## Product Contract hard floor

When a requirements-only unified plan is warranted, these are present inside
`## Product Contract`.

- **Summary** — what is being proposed, in 1-3 lines. Forward-looking.
  Orients the reader before they invest in detail.
- **Requirements** (with stable R-IDs) — what must be true about the
  proposed thing. For very sparse brainstorms (≤3 simple items where the
  bullets ARE the summary), plain bullets without IDs are acceptable; the
  trigger for R-IDs is whether downstream consumers will reference them.
  When requirements span distinct concerns (e.g., "Packaging" /
  "Migration and compatibility" / "Contributor workflow"), group them
  under bold inline headers within the Requirements section — group by
  capability or concern, not by the order requirements were discussed.
  The trigger is distinct concerns, not item count — even four
  requirements benefit if they cover three different topics. Skip
  grouping only when all requirements are genuinely about the same thing;
  a long flat list is a smell that subgroups were missed. R-IDs stay
  continuous across groups (R1, R2 in the first group; R3, R4 in the
  second; never restart at R1 per group).

## Include when material

The agent decides per brainstorm whether each section carries information
that isn't covered elsewhere. Filling a section with placeholder prose is
worse than omitting it.

- **Problem Frame** — include when motivation isn't obvious from Summary
  alone (the *why* needs paragraphs, not a sentence). Backward-looking /
  situational. Does NOT restate the proposal; the remedy lives in Summary.

- **Key Decisions** — include when the brainstorm produced opinionated
  framing choices (defaults, scope narrowings, foundational technical picks)
  that constrain Requirements / Flows / Scope below. Each entry names the
  decision in bold with prose rationale. Sits high in the rendered doc so
  readers encounter the framing choices before descending into detail.

- **Actors** — include when the proposed thing has multi-party behavior
  (multiple humans, agents, or systems meaningfully involved). Skip for
  non-behavioral brainstorms (naming briefs, data-shape briefs, pure
  research, decision frameworks).

- **Key Flows** — include when the proposed thing has multi-step behavior.
  Expected by default for behavioral brainstorms unless the proposed thing
  is genuinely non-flow-shaped (pure API surface, policy, artifact output)
  and Actors / Requirements / Scope Boundaries / Acceptance Examples
  together prevent downstream invention of paths. When omitting from a
  behavioral brainstorm, note the reason in the doc.

- **Visualizations** — a brainstorm earns a visual when a concept has a
  **structure worth showing**, and that decision turns on whether the
  structure exists, *not* on whether your own prose reads clearly. Calling
  your prose "clear enough" is the trap that quietly under-produces the
  visuals a reader actually uses — decide on the shape, not the wording.
  Shapes that warrant one: a data-shape transformation (before/after schema
  or field mapping), a source-of-truth fan-out (one authority feeding many
  derived surfaces), state-or-lifecycle logic, a multi-step flow, an
  entity/relationship structure, a decision boundary, a quantitative
  comparison — and, for any requirement that changes a UI, screen layout,
  component placement, or screen flow, a **wireframe**. This applies to
  backend and conceptual work, not only visual products: a data model, sync
  protocol, or agent workflow earns a conceptual diagram exactly as a UI
  requirement earns a wireframe. Match the visual to the shape — a UI/layout
  shape takes a wireframe in HTML (a mermaid layout diagram or prose in
  markdown; there is no inline-SVG wireframe in markdown), any other structure
  takes a conceptual diagram. A visual is cross-cutting, not a section of its
  own — it sits next to the Key Decision, Requirements group, or Flow it
  illustrates. **A point with nothing structural to show gets no visual** — a
  single-field add, a rename, or a one-line change has no structure, and a
  before/after of one changed line is decoration. One visual per load-bearing
  concept, never decoration or ceremony.

  **Diagrams complement prose; they never replace it.** A diagram is an
  on-ramp to the prose it illustrates, not a substitute. The IDed prose
  (Requirements, Key Decisions, Acceptance Examples) stays complete and
  standalone — a reader who ignores every diagram still gets the full
  content in text, and a downstream agent that reads the artifact as linear
  text is never left with a relationship that exists only in an SVG. Adding
  a before/after diagram is not license to thin the requirement or decision
  prose it depicts.

- **Acceptance Examples** — include when any requirement has a
  state-dependent or conditional shape ("When X, Y") where prose alone leaves
  ambiguity about edge cases. **Always include AEs covering
  behavioral-conditional requirements** — that's where the ambiguity bites
  hardest. Skip when all requirements are unconditional and unambiguous.

- **Success Criteria** — include when there are quality / metric / handoff
  signals that Requirements don't already carry: quantitative metrics ("p95
  latency under 200ms"), qualitative criteria ("the agent's output reads as
  one voice"), process / handoff quality ("spec-doc-review can act on this
  without follow-ups"). Skip when Requirements ARE the success criteria
  (every R is "done when the R is true").

- **Scope Boundaries** — include when scope is contested or there are
  tempting non-goals worth naming explicitly. When the brainstorm is about
  positioning a product against adjacent ones the team could have built but
  is rejecting, split into "Deferred for later" (eventually but not v1) and
  "Outside this product's identity" (positioning decision). Otherwise, a
  single list is fine.

- **Dependencies / Assumptions** — include when material upstream
  dependencies exist or when load-bearing assumptions need to be surfaced.

- **Outstanding Questions** — include when there are unresolved items.
  Distinguish "Resolve Before Planning" (blocks planning) from "Deferred to
  Planning" (answered during planning or codebase exploration).

- **Sources / Research** — surface research that orients the planner or
  justifies framing choices. The test: *"if I were the planner reading this
  cold, would this breadcrumb help me make better choices?"* Yes → surface
  (code locations, external docs, RFCs, constraints, prior plans — the
  category is inclusive, not enumerated). Process exhaust (reading the
  user's prompt, glancing at obvious files) → omit.

  For a load-bearing source fact, retain the repo-relative source ref, the
  source snapshot or observed version, any limitation, and an invalidation
  condition. A `/tmp` dossier may point the current run to quotes, but the
  durable artifact must remain sufficient when that dossier disappears.

  When pausing with a product blocker, `Resolve Before Planning` also names
  the next highest-impact question, its source attempt, and its Product
  Contract write target. Do not add a progress status.

## Agent agency

The catalog is a floor, not a ceiling. When the brainstorm's content doesn't
fit any catalog section, introduce a new one — don't force the content into
a section it doesn't belong in. Content drives section choices, not vice
versa.

The agent also picks per artifact:

- Whether Acceptance Examples render as a separate section or embed in each
  requirement
- How much depth each present section gets

(Requirements grouping is covered above in the Hard Floor item — group by
concern by default, rendering a flat list only when all requirements are
about the same thing, with continuous R-IDs across groups.)

## Brainstorm metadata fields

Every requirements-only unified plan carries a small set of stable metadata fields that
downstream tooling depends on. The contract is format-independent: in
markdown these fields appear as YAML frontmatter at the top of the file; in
HTML they appear as visible header text (typically a `<dl>` of `<dt>`/`<dd>`
pairs or a stats strip). Field names and semantics are the same across both
formats so consumers can locate them without knowing which format produced the
artifact.

### Required

- **`title`** — the artifact's descriptive name with a ` - Plan` suffix
  (e.g., `Highlighter Tool - Plan`), matching the H1 (markdown) or document
  `<h1>` (HTML). It is a unified plan at every readiness state, so the title
  stays stable when `spec-plan` enriches it. Do not put a conventional-commit
  prefix (`feat:`/`fix:`) in the title — the `type` field carries that.
- **`type`** — conventional-commit-prefix-aligned classification (`feat`,
  `fix`, `refactor`, `docs`, etc.).
- **`date`** — creation date in ISO 8601 (`YYYY-MM-DD`), ASCII digits only.
  Used in the filename (`docs/plans/YYYY-MM-DD-NNN-<type>-<topic>-plan.<md|html>`).
- **`topic`** — kebab-case slug identifying the brainstorm subject (e.g.,
  `surface-scope-earlier`, `demo-reel-local-save`). Used in the filename and
  as the resume-detection key when `spec-brainstorm` scans for an existing
  artifact to continue.
- **`artifact_contract`** — always `spec-unified-plan/v1` for new outputs.
- **`artifact_readiness`** — always `requirements-only` for new
  `spec-brainstorm` outputs. Do not use `active`, `in_progress`, `completed`,
  or `done`.
- **`product_contract_source`** — always `spec-brainstorm`.

### Lifecycle status

For a Markdown software unified plan with `artifact_contract:
spec-unified-plan/v1` and `execution: code`, write `status: active` on
creation. Status is independent of readiness: `artifact_readiness` is document
completeness, not lifecycle progress. Do not encode per-unit progress in the
document or infer readiness from status.

HTML output does not carry `status`, and the universal-brainstorming route does
not carry `status`. These outputs remain outside the first lifecycle mutation
contract.

### Field-name stability

Field names are stable across brainstorm revisions — never rename a field
or repurpose its semantics. Agents composing new brainstorms MUST use these
exact names; adding new fields is fine, but renaming `topic` to `subject`
or `date` to `created` breaks filename construction and resume detection.

## ID and content rules

Same shape as plan rules.

- **Stable IDs.** R-IDs (Requirements), A-IDs (if Actors fire), F-IDs (if
  Flows fire), AE-IDs (if Acceptance Examples fire). No other ID namespaces.
- **Plain prefix.** `R1.`, `A1.`, `F1.`, `AE1.` as bullet prefixes. Do not
  bold; the prefix is visually distinctive on its own.
- **Bold leader labels** inside Flows and Acceptance Examples
  (`**Trigger:**`, `**Covers R4, R8.**`) provide structure without deeper
  heading levels.
- **Repo-relative paths.** Always. Never absolute paths.
- **No process exhaust.** No "captured at Phase X" notes, no `## Next Steps`
  pointing to spec-plan, no italic provenance lines. Engineering process
  metadata belongs in commit messages and tool output, not the artifact.
- **No implementation details by default.** Libraries, schemas, endpoints,
  file layouts, code structure stay out unless the brainstorm itself is
  inherently about a technical or architectural change and those details are
  the subject of the decision.

## Discipline: Summary vs Problem Frame

When both sections are present, they earn separate sections only by holding
to different purposes:

| Section | Question it answers | Time direction | Length |
|---|---|---|---|
| `## Summary` | What is this doc proposing? | Forward-looking | 1-3 lines |
| `## Problem Frame` | Why does this proposal exist? | Backward-looking / situational | Paragraphs |

- **Summary doesn't need problem context.** A reader scanning Summary gets
  the proposal at a glance.
- **Problem Frame doesn't restate the proposal.** It establishes the
  situation, the specific moment of pain, and the cost shape — then stops.
  The remedy lives in Summary; restating it in Problem Frame is the
  duplication that makes the two sections feel redundant.

## Rendering

The format-specific references describe how to render these sections in each
output format:

- **Markdown rendering:** `references/markdown-rendering.md`
- **HTML rendering:** `references/html-rendering.md`

This reference (`brainstorm-sections.md`) is about WHAT the brainstorm
contains; rendering references are about HOW each format presents it. The
brainstorm is written in one format — markdown OR HTML, never both — based
on the resolved output mode. The section catalog is the same regardless of
format.