brainstorm

name	brainstorm
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 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 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; 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):

# <module> Brainstorm
...

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). Then stop: the user reads it, and starting the pipeline is how they say it is right.

Step 5: Revision mode

(re-invoked after an abort): re-ask only the affected D dimensions, 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 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.
• 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). 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 — D0–D7 dimensional Q&A checklist + style + trimming rules + diagram conventions.