brainstorm · diff
git:20260907.a691012 to git:20260907.90db501
37 added, 51 removed. Audit A to A.
---
name: brainstorm
description: Use when brainstorming a new module's requirements and architecture into a brainstorm.md, one way to write the intent document the pipeline starts from; not for design.md, RTL, constraints, or any in-pipeline stage.
---
# Pre-Pipeline Requirements Brainstorm
- Run an interactive dialogue with the engineer and write `{module}/intent/brainstorm.md`, one
- way to produce the intent document the pipeline starts from. You run **in your own session,
- before the pipeline** — this conversation never enters the pipeline's context.
-
- Write that one file and nothing else: no `result.json`, no `design.md`, no RTL, no
- constraints. You are not a pipeline stage and no pipeline state exists yet. The document is
- frozen once a run starts, so a requirements change is a fresh invocation of this skill, never
- an edit to an in-flight artifact.
+ Interview the engineer and write `{module}/intent/brainstorm.md`, one way to produce the intent
+ document the pipeline starts from. Run **in your own session, before the pipeline** — this
+ conversation never enters the pipeline's context, and you write no `result.json`.
- Re-invoked after a downstream contradiction was escalated, the existing document is your
- input: what is left to ask is what the change unsettles, and you say in the document which
- parts this round did not touch.
+ The document is frozen once a run starts, so a requirements change is a fresh invocation of
+ this skill, never an edit to an in-flight artifact. Re-invoked that way, the existing document
+ is your input: what is left to ask is what the change unsettles, and you say in the document
+ which parts this round did not touch.
## Where the output goes
- `{module}` is wherever the engineer wants — `~/chips/mydesign`, `./mychip`, `asic/mychip` —
- and is the same path the pipeline is later given as `--module`; its last component is the
- module name. If they named only a module, ask for the directory. Do not invent a parent:
- nothing downstream imposes one, and a guess sends them looking for a tree they did not ask for.
+ `{module}` is any path the engineer wants — the same one the pipeline is later given as
+ `--module`. If they named only a module, ask; do not invent a parent, or you send them looking
+ for a tree they did not ask for.
- Create `{module}/intent/` if absent. That directory is the whole of what the pipeline treats
- as intent, so anything the engineer delivers with the document — a reference model, a register
- map, a standard the document names as authoritative — belongs inside it. A file left at the
- module root is not intent: no stage is handed it and no proof records it.
+ Create `{module}/intent/` and put the document in it, along with anything the engineer delivers
+ that it names as authoritative — a reference model, a register map, a standard. That directory
+ is the whole of what the pipeline treats as intent: a file left at the module root is handed to
+ no stage and recorded by no proof.
## The dialogue
- Settle intent and scope first, and do not enter the rest until it is clear. After that, what
- is left to ask is whatever the material the engineer brought does not already settle — someone
- arriving with a protocol standard and a register map has settled their interfaces and clocking
- in the document they brought, and asking again spends the only thing this dialogue costs. Read
- the material first.
+ What is left to ask is whatever the material the engineer brought does not already settle.
+ Someone arriving with a protocol standard and a register map has settled their interfaces and
+ clocking; asking again spends the only thing this dialogue costs.
- The dialogue is done when none of these is still unspoken for: intent and scope · functions
- and features · top-level IO, and inter-module wires when N>1 · clocks, resets, and every
- crossing between them · architecture partition · timing scenarios · PPA targets · readiness.
- What each one contains you can work out; whether *this* project has settled it, you cannot.
+ It is done when none of these is still unspoken for: intent and scope · functions and features
+ · top-level IO, and inter-module wires when N>1 · clocks, resets, and every crossing between
+ them · architecture partition · timing scenarios · PPA targets · readiness. What each one
+ contains you can work out; whether *this* project has settled it, you cannot.
One question at a time, and end each with the answer you would give and why — a question with
no recommendation makes the user do your work. Where the partition is still open, put 2-3
- candidates side by side so they choose rather than inherit your first idea; where the input
- already fixes it, say so in a line. When a question wants a diagram, the conventions are in
- `skills/specification/references/design-template.md` §Rendering Conventions.
+ candidates side by side so they choose rather than inherit your first idea. For a diagram, the
+ conventions are in `skills/specification/references/design-template.md` §Rendering Conventions.
On readiness, ask whether the stages that author from this document could do so without coming
- back. Their own references say what they need, field by field — read them there. A list kept
- here would be a copy that goes stale while nothing checks it. Name every gap you find, by name.
+ back; their own references say what they need, field by field. Name every gap you find.
## Four things this dialogue is the last chance to settle
- **A number a reference implementation would answer** — a latency, a byte width, a
state-machine cycle count. Settle it here with its source. Deferred, it reaches design.md as
a wrong first draft and a run of Edits on the main thread.
- **Reset polarity, and sync vs async** — deferred, it becomes an SDC-stage guess.
- - **What is deliberately left unconstrained** — a PPA dimension with no bound, a behaviour
- left to the implementer, a bound some outside authority owns. Say so, and say which:
- `specification` writes a row for each of those too and the ledger tells them apart by
- `judge`. What it cannot do is tell a deliberate silence from a forgotten one.
+ - **What is deliberately left unconstrained** — a PPA dimension with no bound, a behaviour left
+ to the implementer, a bound some outside authority owns. Say which: the ledger has a `judge`
+ for each of those, and none for a silence it cannot read.
- **Every open question** — a question is not a proposition, so it gets no ledger row, and the
- document is frozen for the run: a TBD settled later is settled somewhere else.
+ document is frozen: a TBD settled later is settled somewhere else.
## The document, and handing it off
- Write what the engineer would recognize as their own document, one statement per proposition:
- `specification` reads it whole, top to bottom, and transcribes one ledger row per atomic
- proposition in the engineer's words, so a sentence carrying three of them makes that split a
- guess. Nothing reads a heading and no shape is a contract — when the engineer brought a
- document, keep theirs. Descriptive headers and stable names help whoever reads it next.
+ Keep the engineer's own document when they brought one. `specification` transcribes it whole,
+ one ledger row per atomic proposition in their words, and reads no heading — so what you owe is
+ one proposition per statement, not a layout.
- Before handing off, re-read what you just wrote and fix inline any defect that would survive
- the freeze: an unsettled placeholder, a contradiction between two parts of the document (a
- clock named in an interface table but absent from the clock list), or a two-way-ambiguous
- requirement.
+ Re-read what you wrote and fix inline anything that would survive the freeze: a placeholder, a
+ two-way-ambiguous requirement, a contradiction between two parts of the document, or between
+ the document and a file it cites as authoritative.
- Then give the user the on-disk path and a short orientation — the areas covered, and on a
- revision, which ones changed. **Do not echo the document body.** Then stop: the user reads it,
- and starting the pipeline with `--module {module}` is how they say it is right. Nothing is
- dispatchable until that file exists.
+ Then hand over the path and a short orientation — the areas covered, and on a revision, which
+ ones changed. **Do not echo the document body.** Then stop: nothing is dispatchable until that
+ file exists, and starting the pipeline is how the engineer says it is right.