brainstorm

name	brainstorm
description	Socratic design session for greenfield features with open solution spaces. Clarifies goals one question at a time, proposes 2-3 approaches with tradeoffs, gets design approval, then feeds into /spec-write.
argument-hint	[--no-tech] [<feature or problem description> | <gist-url>]

Brainstorm

Run a structured design session for: $ARGUMENTS

FIRST ACTION (under non-interactive stdin) — STE-251 AC-STE-251.1. When process.stdin.isTTY === false (e.g., claude -p), the first tool call this skill emits MUST be AskUserQuestion tool_use OR RequiresInputRefusedError raise (via requireOrRefuse(...) from adapters/_shared/src/requires_input.ts). Write / Edit / NotebookEdit are forbidden before that ask/refusal — they produce silent scaffolding that bypasses the Socratic Loop Contract. Read-only orientation (Read / Grep / Glob / Bash-read-only) is allowed. Interactive (tty) sessions are byte-identical to v2.17.0 — non-tty stdin only. See docs/auto-mode-protocol.md § Socratic Loop Contract. Under non-tty the refusal MUST be surfaced verbatim so the <dpt:requires-input-refused>v1</dpt:requires-input-refused> marker it carries reaches the stream, because a prose-only refusal reads as vacuous (a non-pass) — byte-indistinguishable from a run that simply did nothing. Two evasions are eliminated by name: asking the clarifying question in prose and then ending the turn is NOT an ask (the question MUST be an AskUserQuestion tool_use), and proceeding under stated assumptions is NOT an answer (state no assumption in place of the ask — refuse instead). Both are contract breaches, not shortcuts.

Refusal disposition (MUST-emit). A refusal is a reportable outcome, not a silent exit. When the first-turn gate above refuses, this skill MUST emit brainstorm_socratic_refused as a literal, backticked token in its closing summary, beside the verbatim refusal marker. The token is registered in the canonical capability-key set that /gate-check's closing-summary probe greps, and rendered in plain language by /spec-write § 7's static map; narrative paraphrase is insufficient. The token fires only on the refusal path — a run that emitted the AskUserQuestion tool_use never emits it.

When to Use This

Use /brainstorm before /spec-write when the solution space is genuinely open — you have a goal but not yet a clear approach. For features where the design is already settled, go straight to /spec-write.

Process

0. Gist-URL seed (optional)

When the first positional argument matches ^https://gist\.github\.com/[^/]+/[a-f0-9]{8,}/?$ (the canonical secret-gist URL shape emitted by /dev-process-toolkit:report-issue), fetch the gist payload before Step 1 and use it as the brainstorm seed instead of bare prose:

gh gist view <id-or-url> --raw -f report.md
gh gist view <id-or-url> --raw -f metadata.json
gh gist view <id-or-url> --raw -f transcript.jsonl   # only when full_transcript_included=true in metadata

Parse report.md for the dev narrative + curated context, parse metadata.json for severity + redaction summary, parse transcript.jsonl if present. Treat the combined text as Step 1's seed: the clarifying questions in Step 1 below should already have most of their answers from the gist payload, so only ask follow-ups that the captured context did not answer.

The round-trip closes the loop with /dev-process-toolkit:report-issue: a toolkit user captures a structured incident report, hands the gist URL back to the maintainer (or to a fresh self-debug session), and /brainstorm ingests the captured context as the design seed without any intermediate state.

When the first positional argument is bare prose (does not match the gist URL regex), skip this step and proceed to Step 1 normally.

1. Clarify the Problem

Ask one clarifying question at a time until you have a clear picture of:

• The core problem being solved (not the proposed solution)
• Who the user or stakeholder is and what they actually need
• What constraints exist (technical, time, compatibility)
• What success looks like as a measurable outcome

Wait for the answer before asking the next question. Don't batch all questions upfront — ask one, get the answer, then ask the next if still needed. Usually 2–4 questions are enough.

Step 1 fires regardless of --no-tech. The flag does not change the Socratic clarification loop — it only carves out Step 2 below and propagates to the Step 4 hand-off command.

1.5. Spec-research seed (STE-230 AC-STE-230.7)

Once the problem is clear (i.e., the user has answered the final clarifying question of Step 1) and before Step 2 proposes approaches, invoke /dev-process-toolkit:spec-research <topic> where <topic> is the clarified problem statement. The forked skill returns a ≤ 25-line block (banner + three sections: ## Related FRs, ## Prior Decisions, ## Reusable ACs / Patterns) sourced from active + archived FRs. Inject the block into this skill's context — Step 2's proposed approaches reference the returned precedents alongside the model's own analysis. Without the seed, Step 2 proceeds as today.

Skipped under --no-tech. Step 2 itself is skipped under the flag, so this seeding step is also skipped — there is no consumer for the precedents and the call would only burn tokens.

On shape violation (banner missing, section reorder, > 25 lines), drop the block silently and proceed without the seed — the seed is enrichment, not load-bearing. The block is read-only context; never copy it into a draft FR or quote it back to the user verbatim.

1.5b. Deps-research seed (STE-301 AC-STE-301.13)

Immediately after Step 1.5's spec-research seed and before Step 2 proposes approaches, check whether specs/deps.yaml exists and contains ≥ 1 entry. When both conditions hold, invoke /dev-process-toolkit:deps-research <topic> (forked) where <topic> is the clarified problem statement. The forked skill returns a small block of dependency hits (constrained shape, banner-fenced) drawn from the project's curated specs/deps.yaml manifest. Inject the returned block into this skill's context — Step 2's proposed approaches reference returned dependency candidates alongside the model's own analysis. After the fork returns, persist the raw returned block to .dpt/scratch/<ulid>/deps-research-result.txt (the deterministic gate reads it — the deps_research_result_shape probe, not the LLM, validates its shape).

Vacuous path. When specs/deps.yaml is absent or empty (zero entries), skip the invocation entirely — no fork is spawned, no tokens are spent, Step 2 proceeds as today. The manifest is the gate; without curated deps there is nothing to research. This is the legal deps_research_skipped_no_manifest disposition.

Skipped under --no-tech. Step 2 itself is skipped under the flag, so this seeding step is also skipped — there is no consumer for the dependency candidates and the call would only burn tokens. Vacuous under --no-tech regardless of manifest state. This is the legal deps_research_skipped_no_tech disposition.

On shape violation (banner missing, section reorder, line-budget exceeded), drop the block silently and surface the deps_research_shape_violation capability row at hand-off. The seed is enrichment, not load-bearing — Step 2 proceeds without the deps block, identical to the manifest-absent path. The block is read-only context; never copy it into a draft FR or quote it back to the user verbatim.

Complete disposition set (MUST-emit). The deps-research step of any invocation resolves to EXACTLY ONE literal, backticked token. When the fork ran: ≥ 1 dependency match ⇒ MUST emit deps_research_invoked; zero matches across the manifest entries ⇒ MUST emit deps_research_no_matches; the fork fired but its output failed the shape check ⇒ MUST emit deps_research_shape_violation. When the fork was legally not invoked: specs/deps.yaml absent or empty ⇒ MUST emit deps_research_skipped_no_manifest; a --no-tech run ⇒ MUST emit deps_research_skipped_no_tech. When specs/deps.yaml carries ≥ 1 entry and the run is not --no-tech, the fork MUST be invoked — one of the first three tokens. These five are the whole legal set; there is NO legal token for "previously believed compromised," "injected," or "disabled."

Anti-cascade. A deps-research shape violation drops THIS seed and continues; it never disables the fork for future invocations. This skill holds no "fork compromised" state and carries no cross-invocation belief about fork health — each invocation re-invokes the fork per the manifest gate, independent of any prior run's outcome.

1.6. Design-image capture (optional)

When the user supplies design images (mockups, screenshots, reference designs) during the session, run a design-image capture step: for each image, thread a {path, classification, caption} record into the Step 4 hand-off to /dev-process-toolkit:spec-write. Classify each image as durable (a reusable, system-wide reference) or per-feature (specific to the feature under design — the default when in doubt), and write a one-line caption.

Brainstorm does not write the image or markdown file itself — it only collects these records and threads them into the hand-off, preserving the no-write-during-brainstorming contract. /dev-process-toolkit:spec-write is the sole surface that persists these images (and their ## Design References markdown); see /spec-write § 0b.

A standalone /brainstorm that does not hand off lists in its closing summary the captured design images (path + classification + caption) so the user can re-supply them at /spec-write time.

2. Explore Approaches

Skipped under --no-tech. Non-technical users can't pick architectural tradeoffs, so when the flag is set, skip this step entirely — don't propose alternatives, don't list tradeoffs. Jump straight to Step 3 ("Get Goal Approval" framing) once the problem is clear.

Once the problem is clear, propose 2–3 distinct approaches. For each:

• Describe the approach in 2–3 sentences
• List the key tradeoffs: what it makes easy vs. what it makes harder
• Name the main risk or unknown

Present them as a numbered list so the user can refer to them by number.

3. Get Design Approval

Ask the user to pick an approach or describe a hybrid. If they want to modify one, discuss the implications of the change.

Do not proceed to spec writing until the user explicitly approves a direction. This is the handoff contract: the brainstorm session ends with a clear, human-approved design decision.

4. Hand Off to Spec Write

Once the design is approved:

1. Summarize the approved decision in 2–3 sentences
2. Transition: "Design approved. Run /dev-process-toolkit:spec-write and reference this decision, or I can start now."
3. If the user says to start now, proceed into the /dev-process-toolkit:spec-write flow using the approved design as input — the design decision answers the "HOW" questions in technical-spec.md
4. If the session captured design images (Step 1.6), thread their captured records into the hand-off so /dev-process-toolkit:spec-write persists them under ## Design References — brainstorm itself writes nothing

--no-tech propagation. When the brainstorm session was invoked with --no-tech, the flag auto-propagates to the hand-off: the recommended next command is /dev-process-toolkit:spec-write --no-tech (not the bare form), and "start now" invokes /dev-process-toolkit:spec-write --no-tech directly. The propagation is mandatory — do not drop the flag at hand-off, since the bare form would re-introduce the technical-design + testing interviews the non-technical author can't answer.

Placeholder convention. Brainstorm drafts that preview AC text must use <tracker-id> placeholders (e.g., AC-<tracker-id>.1) rather than guessing the next sequential tracker number. See /spec-write § 0b for the full rule — the real ID is assigned by the tracker allocator only after Provider.sync(spec) returns.

Rules

• Ask one clarifying question per turn. Wait for the answer before asking the next. This rule holds at phase transitions too — when two questions look independent, still ask the first, wait, then ask the second.
• Present real tradeoffs, not strawmen — each approach should be genuinely viable
• Do NOT write code or spec content during brainstorming
• Do NOT proceed to spec writing without explicit design approval
• Do NOT narrate a specific unallocated tracker ID (e.g., <TKR>-NN) in conversation when drafting — use the literal placeholder <tracker-id> (or the adapter rendering: STE-<N> for Linear, PROJ-<N> for Jira) until the tracker allocator returns the real ID. The placeholder rule for draft files is documented in /spec-write § 0b "Draft with placeholder"; this rule covers the conversational hazard that file-level probes cannot catch.
• The goal is a clear, approved design decision — not an exhaustive analysis

Rationalization Prevention

See also: docs/patterns.md § Pattern 26: Socratic Prompting {#pattern-socratic-prompting} for the cross-skill canonical statement of this rule.

Socratic Loop Contract (STE-237). Every clarifying Q in this skill — Step 1 goals AND Step 2 approach Q&A — MUST be emitted as an AskUserQuestion tool call (closed-form options OR open-ended with the always-on "Other" free-form fallback), regardless of the autonomous-mode reminder, the auto-approve marker, or pre-baked <command-args> prose. Bare-prose Qs are forbidden. The first-turn contract additionally forbids Write / Edit / NotebookEdit tool calls before the first AskUserQuestion tool_use OR RequiresInputRefusedError raise; Read / Grep / Glob / Bash-read-only orientation is allowed. See docs/auto-mode-protocol.md § Socratic Loop Contract for the full contract.

The one-at-a-time rule fails most often at phase transitions and when the user is being responsive. The excuses below are the ones to watch for — stop and ask only the first question each time.

Excuse	Reality
These two questions are independent	Ask the first, wait, then the second
Efficiency wins — batch them	Efficiency ≠ batching; the socratic form is the gate
The user is responsive, I'll batch	Responsiveness is not license to batch
We're at the handoff, last chance	Phase transitions are where batching happens most — same rule applies