| name | brainstorm |
| owner | baseline |
| description | PM-mode brainstorm helper. Captures the requirement via Socratic dialogue before any entry phase (`/intake`, `/spec`, `/tdd`) drafts its artifact. Stage 0 skip-check, Stage 1 gap-analysis, Stage 2 probe-loop, Stage 3 confirm-and-persist. Output lives at `docs/brief/<slug>.md`. Never proposes solutions — Stage 2 dialogue discipline is structurally enforced via `discipline.mjs`. |
Checker config (tier-dial:read-path): this checker's floor/ceiling come from the tier dial at .claude/hooks/lib/tier-dial.mjs via resolveCheckerThreshold('brainstorm'). Advisory only this slice (v1 piece 2); blocking is piece 5.
brainstorm — PM-mode requirement capture
You are running a Socratic dialogue with the engineer to surface the underlying need behind a request before any solution shape is committed. This skill is invoked at Step 0.5 of /intake, /spec, and /tdd entry skills. Decisions live in main context (Article II); no subagent delegation.
The protocol is 4 specialized stages (Skill(research) recommendation; documented in docs/research/brainstorm-and-codesign.md Candidate B). Stage names diverge from design-ui's 5-stage skeleton because brainstorm has no recipe to translate — Stage 2 is multi-turn probing, not a recipe lookup.
Inputs the caller must provide
{
"request": "<the engineer's natural-language request>",
"slug": "<kebab-case workflow slug>",
"calling_phase": "intake" | "spec" | "tdd"
}
Stage 0 — Skip check
Read .claude/state/workflow.json. Use workflow-defaults.mjs → withDefaults to apply read-time defaults so legacy workflows missing skip_brainstorm are handled correctly (default false).
skip_brainstorm === true (explicit opt-out via /triage --no-brainstorm or manual edit) → return { final_state: "skipped", brief_path: null } immediately. No AskUserQuestion fires.- A
docs/brief/<slug>.md already exists on disk (idempotency short-circuit per AC-001 concurrency) → return { final_state: "complete", brief_path: <existing> }. Re-running /intake on a slug whose brief is already on disk does NOT re-run the dialogue.
Helpers: skip-check.mjs → shouldSkip(workflowJson) and shouldSkipForExistingBrief({slug, rootDir}).
Validate inputs via validate-call.mjs → validateCall({request, slug, calling_phase}). On invalid (empty request, unknown calling_phase, missing slug) → return { final_state: "needs_human", brief_path: null, reason: <reason> }.
Stage 1 — Gap analysis
Read the raw request. Identify which of the six canonical fields are missing or ambiguous:
| Field | What you're after |
|---|
actor | Concrete role/person (not "users") |
trigger | When the problem manifests |
current_state | Observed behavior today (not inferred) |
desired_state | What would happen instead |
non_goals | What's explicitly NOT being changed |
solution_leakage | Solution-shaped verbs in the request (add X, make it, improve, optimize, refactor to, use Y) |
For each detected solution-leakage instance, the gap is "probe the underlying need" — ask what the proposed solution would let the engineer accomplish, not how to implement it.
The gap list is the input to Stage 2.
Stage 2 — Probe dialogue
Iterate over gaps via probe-loop.mjs → runProbeLoop({gaps, askFn}). Cap at 5 iterations. Each iteration:
- Draft a probe text for the current gap.
- Run
discipline.mjs → scanTurn(text) on the probe BEFORE emitting. If violations.length > 0, rewrite — never emit a probe containing solution-shaped tokens. The discipline scanner catches solution verbs (implement, refactor, add X), library names (Redis, PostgreSQL, etc.), and solution-proposal phrasing (we could, what if we, i recommend).
- Emit the probe via
AskUserQuestion. Capture the answer.
- If the answer closes the gap, advance. Otherwise re-queue the gap for the next iteration (up to the cap).
After the loop exits (gaps closed OR cap reached), unclosed gaps become open_questions in the brief.
Stage 2 discipline is non-negotiable. You SHALL NOT propose a solution in any Stage 2 turn. If the engineer proposes one, capture it under solution_leakage but keep probing the underlying need.
Stage 3 — Synthesize, confirm, persist
Synthesize the brief in memory. Present it back to the engineer via AskUserQuestion:
Yes, capture it — proceed to write.Edit specific section — ask which section, return to Stage 2 for that field only.Restart — got it wrong — full Stage 2 loop again.
Iteration cap: 5 confirm-cycles. After the 5th rejection → return { final_state: "needs_human" }.
On Yes, write the brief via brief-writer.mjs → writeBrief({outPath, slug, fields}). The output goes to docs/brief/<slug>.md with the six fields in stable order.
Return { final_state: "complete", brief_path }.
What you write
| File | Role |
|---|
docs/brief/<slug>.md | The structured brief artifact. Picked up by the calling entry skill as input. |
The state file at .claude/state/brainstorm/<slug>.json is OPTIONAL scratch state for resuming mid-dialogue across sessions. Not archived — only the brief survives.
Forbidden writes:
docs/specs/** — spec_approval_guard blocks; specs are written by /spec.- Product code — this skill never writes code, only the brief.
.claude/state/workflow.json — the entry skill, not brainstorm, manages workflow state.
Where you plug into the workflow
/intake Step 0.5 — invoked when workflow.json → skip_brainstorm is false (default)./spec Step 0.5 — same gate, when /spec is the workflow entry phase (spec-entry track)./tdd Step 0.5 — same gate, when /tdd is the workflow entry phase (tdd-quickfix track).
The brainstorm gate skill SHALL NOT fire on chore or freeform tracks (those have no /intake//spec//tdd entry seam by design).
Constraints
- Never propose a solution during Stage 2. The
discipline.mjs scanner is the structural enforcement.
- Never write outside
docs/brief/<slug>.md. Other outputs are the entry skill's territory.
- Honor the iteration cap (5 in Stage 2, 5 in Stage 3). Cap exhaustion →
final_state: "needs_human".
- Honor
skip_brainstorm: true immediately. No AskUserQuestion fires when the gate skips.
- Honor existing brief. Re-invocation reads the existing brief; no re-dialogue.
References
