brainstorm · diff
git:20260802.fb52ea0 to git:20260806.6fea301
20 added, 22 removed. Audit A to A.
---
name: brainstorm
- description: Use when brainstorming a new module's requirements and architecture to produce an approved brainstorm.md before the pipeline; not for design.md, RTL, constraints, or any in-pipeline stage.
+ description: Use when brainstorming a new module's requirements and architecture to produce the brainstorm.md the pipeline starts from; not for design.md, RTL, constraints, or any in-pipeline stage.
---
# Pre-Pipeline Requirements Brainstorm
Own the interactive D0–D7 brainstorm dialogue and produce a frozen
`{module}/brainstorm.md`. Run **in your own session, before** the design
pipeline: the brainstorm conversation never enters the pipeline's context. The pipeline
- starts only after `brainstorm.md` reaches `Status: approved`, and reads that file solely
- inside its sub-agent contexts (it is the pipeline's input, not a pipeline stage).
+ starts when the user starts it and reads that file solely inside its sub-agent contexts
+ (it is the pipeline's input, not a pipeline stage).
## When to Use
- A new module needs its requirements + architecture settled before the pipeline.
- A requirements contradiction surfaced downstream and was escalated for revision: the
user aborts, re-invokes this skill in revision mode, re-approves.
## Iron Rule
- You are **pre-pipeline**: write exactly one artifact, `{module}/brainstorm.md`
(creating `{module}` if absent, before the module enters the pipeline). Write
**no** `result.json`, and you are **not** a pipeline stage — you run before any pipeline state exists.
- **Do not author design.md / RTL / constraints / any downstream artifact.** Your
output is the brainstorm only; `design.md` is derived from it downstream.
- - `brainstorm.md` is **immutable once approved** for the duration of a run. A requirements
- change is handled by re-invoking this skill in revision mode and re-approving — never
- edit an in-flight artifact to absorb a change.
+ - `brainstorm.md` is **frozen for the duration of a run**. A requirements change is handled
+ by re-invoking this skill in revision mode, never by editing an in-flight artifact to
+ absorb the change: every proof downstream records the fingerprint it read.
## Input Artifacts
| Variable / input | Purpose |
|---|---|
| `{module}` | The module's directory — the same path the pipeline is later given as `--module`, and where its whole work tree goes. Anywhere the user wants: `~/chips/mydesign`, `./mychip`, `asic/mychip`. Its last component is the module name, which titles the brainstorm. |
| User-provided material (optional) | Public spec / reference docs the user pastes or points to. |
No fixed external inputs. Revision mode additionally reads the existing
`{module}/brainstorm.md`.
Ask for the directory if the user named only a module. Do not invent a parent for them:
nothing downstream imposes one, and a guess sends them looking for a tree they did not ask for.
## Output Artifacts
| Path | Schema / Format | Use |
|---|---|---|
- | `{module}/brainstorm.md` | Custom markdown; frontmatter `Status: draft\|approved`; descriptive ATX sections per the checklist's Section Layout | The pipeline's frozen input. |
+ | `{module}/brainstorm.md` | Custom markdown; descriptive ATX sections per the checklist's Section Layout | The pipeline's frozen input. |
`brainstorm.md` lives at the **module root**, NOT under any stage workdir. There
is **no** `version` frontmatter field (re-derivation after a revision is given naturally
by the fresh run's empty workdir).
## Workflow
### Step 1: Settle `{module}` + read any user-provided material
### Step 2: D0–D7 dimensional brainstorm dialogue
(one question at a time, multiple-choice
preferred; D0 first; D4 presents 2–3 candidate architectures with side-by-side
mermaid): see `references/brainstorm-checklist.md`.
### Step 3: Write `{module}/brainstorm.md`
with descriptive section headers per the
- checklist's Section Layout (create `{module}` if it does not exist), with
- frontmatter:
+ checklist's Section Layout (create `{module}` if it does not exist):
```markdown
- ---
- Status: draft
- ---
-
# <module> Brainstorm
...
```
- ### Step 4: Approval gate (path-handoff)
+ ### Step 4: Hand off the path
First re-read the just-written `brainstorm.md` and
fix inline any defect that would survive the freeze: a placeholder / unsettled `OQ-NN`,
a cross-dimension contradiction (e.g. a clock in a D2a clock-domain column but absent
from the D3 clock list), or a two-way-ambiguous requirement. Then point the user to the
on-disk path + a short orientation (the D-dimensions covered; revision mode: only the D
sections changed this round). **Do not echo the brainstorm body** (sections / tables /
- mermaid / code). On explicit user agreement, set frontmatter `Status: approved`. While
- `Status: draft`, do not hand off to the pipeline.
+ mermaid / code). Then stop: the user reads it, and starting the pipeline is how they say
+ it is right. Nothing in the file records that agreement, because nothing downstream reads
+ such a record — an approval field would be a second place to look for a decision the user
+ already made by acting on it.
### Step 5: Revision mode
(re-invoked after an abort): re-ask only the affected D dimensions,
- preserve the rest, then re-run the Step 4 approval gate (its self-review re-reads the
+ preserve the rest, then re-run Step 4 (its self-review re-reads the
whole doc, so a changed dimension contradicting an untouched one is caught).
## Red Flags
| Excuse | Reality |
|---|---|
- | "The requirements changed — I'll just edit the approved brainstorm to absorb it" | Absorb a requirements change by re-invoking in revision mode + re-approving — never by editing an in-flight artifact (Iron Rule: `brainstorm.md` is immutable once approved). |
+ | "The requirements changed — I'll just edit the brainstorm to absorb it" | Absorb a requirements change by re-invoking in revision mode — never by editing an in-flight artifact (Iron Rule: `brainstorm.md` is frozen for the run). |
## Completion Gate
- - `{module}/brainstorm.md` exists with frontmatter `Status: approved`.
+ - `{module}/brainstorm.md` exists.
- The brainstorm covers the D0–D7 dimensions reached (D0 intent settled; D4 had 2–3
candidates; feature IDs / interface-group names / scenario IDs are stable named
anchors per the checklist's "Subsection IDs" section).
- The brainstorm body was **not** echoed into the conversation (path-handoff only).
- No `result.json` / pipeline-state command issued (Iron Rule — pre-pipeline).
## Return Contract
- Control returns to the user. Produce only `{module}/brainstorm.md` (no `result.json`, no state files — per the Iron Rule). After approval, the user starts
- the pipeline with `--module {module}`; its entry gate verifies the approved brainstorm before the
- first stage consumes it.
+ Control returns to the user. Produce only `{module}/brainstorm.md` (no `result.json`, no
+ state files — per the Iron Rule). The user starts the pipeline with `--module {module}`
+ when they are satisfied with what is on disk; the kernel will not dispatch `specification`
+ until that file exists.
## Bundled References
- [`references/brainstorm-checklist.md`](references/brainstorm-checklist.md) — D0–D7 dimensional Q&A checklist + style + trimming rules + diagram conventions.