/ia-brainstorming

name: ia-brainstorming
class: workflow
description: >-
  Pre-implementation exploration: deep interview, approach comparison, design
  doc. Use when exploring a vague feature idea, clarifying ambiguous
  requirements, or comparing approaches before coding. For the full workflow,
  use the ia-brainstorm command (Claude Code).

Brainstorming

Clarify **WHAT** to build before **HOW** to build it.

Hard Gate

**No implementation until the design is approved.** Brainstorming produces a design document, not code. Do not invoke implementation skills, write production code, or create files outside `docs/brainstorms/` until the user explicitly approves the design and moves to planning.

Core Process

Phase 0: Assess and Ground

Before diving into questions, do two things:

**Ground in the codebase (when applicable).** If the brainstorm relates to existing code, read the relevant modules, patterns, and constraints before generating options. This prevents suggesting approaches that conflict with the actual architecture. Skip for purely abstract brainstorms (tech choices, product direction) where no codebase context applies.

**Right-size the artifact.** Match ceremony to problem size. If the brainstorm resolves in 3 messages, don't force a formal design doc -- a summary comment is enough. If it spans multiple sessions and touches architecture, write the full Phase 3 doc. No ceremony tax.

**Assess whether brainstorming is needed.** Brainstorm when any of these fire: vague terms ("make it better", "add something like"), multiple reasonable interpretations, undiscussed trade-offs, user uncertainty, solution-framing instead of problem-framing ("build a dashboard"), or request spanning multiple independent subsystems (decompose first — see Scope Decomposition below). Otherwise, requirements are clear — suggest: "Your requirements seem clear. Consider proceeding directly to planning or implementation."

Scope Decomposition Gate

If the request describes multiple independent subsystems (e.g., "build a platform with chat, file storage, billing, and analytics"), flag this immediately. Don't spend questions refining details of a project that needs decomposition first.

1. Identify the independent pieces and how they relate 2. Determine build order (dependencies, shared infrastructure first) 3. Brainstorm the first sub-project through the normal Phase 1-3 flow 4. Each sub-project gets its own spec -> plan -> implementation cycle

Phase 1: Understand the Idea

**User context calibration (before diving into the idea):**

Read signals from the user's first message to calibrate communication register:

• **Vocabulary**: Are they using technical terms (API, schema, migration) or describing experiences (it's slow, it breaks when...)?
• **Framing**: Are they describing a solution ("build a dashboard") or a problem ("I can't see what's happening")?
• **References**: Are they pointing to code, files, and patterns, or to analogies and comparisons ("something like Notion")?

Adjust question style accordingly. Technical users get architecture-level probing. Non-technical users get experience-level probing. Don't ask about this calibration -- just do it. If signals are ambiguous, default to the vocabulary the user is already using.

**Explore project context first:** Before asking questions, read existing files, docs, and recent commits related to the idea. Understanding what exists prevents asking questions the codebase already answers and grounds the conversation in reality.

Ask questions **one at a time** by default. When probing a single dimension (e.g., data model, auth flow), clustering 2-3 related questions together is acceptable.

**Info-dump gate (when user offers rich context up-front):** if the user's first message is substantial (>200 words, or dumps requirements in stream-of-consciousness), resist the urge to ask questions one-at-a-time. Instead, respond with 5-10 **numbered clarifying questions** the user can answer in shorthand (`1: yes, 2: channel #ops, 3: no because backwards compat`). Pick questions that remove ambiguity, not questions that show you read the dump. Exit this batched mode when the user's answers show they can be asked about edge cases without basics being explained back to them.

Example after a spec dump:

Before I propose approaches, quick clarifications:

1. Auth — SSO (which provider?) or username/password?
2. Sync or async for the webhook delivery?
3. Which of the three integrations is P0?
4. "Fast enough" in the spec — what's the actual number?

Answer whichever you know; leave blanks for the rest.

**Question Techniques:**

1. **Prefer multiple choice when natural options exist.** Good: "Notification: (a) email, (b) in-app, (c) both?" Avoid: "How should users be notified?" 2. **Start broad, then narrow.** Core purpose → users → constraints. 3. **Validate assumptions and probe success early.** "I'm assuming users are logged in — correct?" / "How will you know this is working?"

**Key Topics to Explore:**

| Topic | Example Questions | |-------|-------------------| | Purpose | What problem does this solve? What's the motivation? | | Users | Who uses this? What's their context? | | Constraints | Any technical limitations? Timeline? Dependencies? | | Success | How will you measure success? What's the happy path? | | Edge Cases | What shouldn't happen? Any error states to consider? | | Existing Patterns | Are there similar features in the codebase to follow? | | Non-goals | What is explicitly NOT in scope? |

See [deep-interview.md](./references/deep-interview.md) for deep interview techniques, including **rigor probes** (evidence/specificity/counterfactual/attachment as open-ended forced production, not menus), the **blindspot pass** for domains the user can't evaluate, and the **integration check** that fires before Phase 1 exit when combining stated answers + agent defaults produces an unsurfaced downstream effect.

**Exit Condition:** Continue unt