---
name: brainstorming
description: "Formal design-brainstorming process. MUST use before any creative work, feature creation, or behavior change. Explores intent, requirements, and design through collaborative dialogue before a single line of implementation."
---

# Brainstorming Ideas Into Designs

Turn vague ideas into fully formed designs and specs through structured collaborative dialogue.

## Trigger

Use this skill whenever the user asks for:
- A new feature, component, or tool
- A modification to existing behavior
- Any creative or design work
- Anything that could be described as "build X" or "add Y"

## Hard Gate

**Do NOT invoke any implementation skill, write code, scaffold projects, or take implementation action until a design has been presented and the user has approved it.** This applies regardless of perceived simplicity. Even a config change or single-function utility gets a design (it can be a few sentences).

## Process

Follow this sequence strictly. One step at a time.

### 1. Explore Project Context
- Check existing files, docs, recent commits, and codebase structure
- Assess scope: if the request spans multiple independent subsystems (chat + billing + analytics), flag it immediately and decompose before refining details
- For greenfield projects, confirm it's truly greenfield

### 1.5 Grounding Scan (Compound Engineering)
- Before ideating, check `docs/solutions/` for prior learnings relevant to this topic
- Check `CONCEPTS.md` for domain vocabulary that constrains the design space
- If prior learnings exist, factor them in: "Last time we solved X, we learned Y" — this is the compound advantage
- Use `search_files` to find relevant solutions: `search_files("topic_keyword", path="docs/solutions/")`
- Also query Hindsight for semantically related learnings: `hindsight_recall("topic description")` — catches solutions that keyword search misses (e.g. "Galera bootstrap failure" finds a doc titled "Sequential SST Recovery")
- Merge both sources: file hits give full detail, Hindsight hits give semantic matches + cross-project patterns

### 1.6 Scope Assessment
Classify the work before proceeding — match ceremony to size:
- **Lightweight** — small, well-bounded, low ambiguity → brief alignment, short doc
- **Standard** — normal feature or bounded refactor with some decisions → full process
- **Deep** — cross-cutting, strategic, or highly ambiguous → extended exploration, sub-agent grounding
- If scope is unclear, ask one targeted question to disambiguate, then proceed

For Deep scope, also classify: **feature** (existing product shape anchors decisions) vs **product** (brainstorm must establish product shape itself). Product-tier triggers additional questions about primary actors, core outcome, and positioning.

### 1.7 Blindspot Pass (when user signals unfamiliarity)
If the user signals they lack domain knowledge ("I know nothing about X", "never touched the auth modules"):
- Map the decision surface BEFORE asking questions — lay out the territory
- List the areas where decisions will need to be made
- For each area, note what's known vs unknown
- Then begin targeted questions from a position of mapped terrain, not blind exploration

### 1.8 Visual Probe Tripwire
If the feature is inherently visual or spatial (drawing/canvas tools, UI layout, interaction states, charts, diagrams, maps, timelines):
- Offer a visual companion immediately, not just-in-time
- Use `browser_vision` to show mockup comparisons or layout sketches
- Visual decisions should be shown, not described

### 2. Offer Visual Companion (Just-in-Time)
- Do NOT offer upfront
- Only offer when a question would genuinely be clearer shown than described (mockups, layout comparisons, architecture diagrams)
- Offer as a standalone message; wait for yes/no before proceeding
- If declined, continue text-only and don't offer again unless the user raises it

### 3. Ask Clarifying Questions — One at a Time
- Only one question per message
- Prefer multiple choice when possible
- Focus on: purpose, constraints, success criteria, audience
- Break complex topics into multiple sequential questions

### 4. Propose 2–3 Approaches
- Present options with trade-offs
- Lead with your recommendation and reasoning
- Keep options realistic; no strawmen

### 5. Present Design Sections — Incrementally
- Scale each section to its complexity (few sentences to ~200 words)
- Ask after each section: "Does this look right?"
- Cover: architecture, components, data flow, error handling, testing
- Design for isolation: each unit should have one clear purpose, well-defined interface, and be testable independently

#### Product Contract (for Standard/Deep scope)
For non-lightweight work, the design doc should include a Product Contract:
- **Primary actors** — who uses this and how
- **Success criteria** — measurable outcomes, not just "it works"
- **Scope boundaries** — explicit non-goals (what we're NOT building)
- **Acceptance examples** — concrete scenarios that define "done"
- **Key flows** — the user journeys this enables or changes
- Keep implementation details OUT of the Product Contract — libraries, schemas, endpoints belong in planning

### 6. Write Design Doc
- Save to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` (or user-preferred location)
- For Standard/Deep scope, use the Product Contract structure above
- Commit to git if in a repo

### 6.5 Verdict Routing (Compound Engineering)
During exploration, if the conversation converges on "should we adopt/switch to/revisit a specific technology X":
- This is a verdict question, not a brainstorming question
- Route to the `tech-pov` skill: it gives a decisive, project-grounded verdict
- Offer the handoff interactively: "This looks like a technology decision — want me to evaluate X against our project with a structured verdict?"
- On decline, continue the normal brainstorming workflow

### 7. Spec Self-Review
- **Placeholder scan:** Fix any TBD/TODO/incomplete sections
- **Internal consistency:** Ensure architecture matches feature descriptions
- **Scope check:** Confirm it's focused enough for one implementation plan
- **Ambiguity check:** Remove any requirement that could be interpreted two ways

### 8. User Review Gate
- Ask the user to review the written spec before proceeding
- Wait for approval; make changes and re-review if requested

### 9. Transition to Implementation
- **Invoke the `writing-plans` skill** to create the implementation plan
- Do NOT invoke frontend-design, mcp-builder, or any other implementation skill directly

## Pitfalls

- **Load the skill BEFORE generating brainstorming content.** When a user says "brainstorming first", "let's brainstorm", or similar, load this skill IMMEDIATELY and follow its structured process (one question at a time, multiple choice, incremental validation). Do NOT dump a full ad-hoc analysis first and then load the skill afterward — the structured process IS the value, not the ideas themselves. The user asking for the skill after you've already brainstormed is a correction signal.

- **One question at a time** — don't overwhelm
- **Multiple choice preferred** — easier to answer than open-ended
- **Incremental validation** — present design, get approval before moving on
- **Implicit Approvals:** On Telegram/Slack, short confirmations like "Ja", "Passt", or "Go" are valid approvals. Do NOT demand formal section-by-section confirmation.
- **Explore alternatives** — always propose 2–3 approaches
- **Follow existing patterns** — in existing codebases, match current conventions

- **Informal approvals in text-only channels** — On Telegram, Slack, or similar, users may approve designs with short messages like "ja", "passt", "looks good", or "go ahead" rather than explicit section-by-section confirmation. Treat these as valid approvals and proceed. Do NOT demand formal "yes, section 3 is approved" wording.
- **User provides credentials mid-process** — If the user shares an API key or password during brainstorming, accept it immediately, apply it, and continue. Do NOT halt the flow to ask them to set it themselves; security handling (env vars, no hardcoding) happens in implementation.

## After the Design

The terminal state of this skill is invoking `writing-plans`. Do NOT proceed to coding or any other implementation action without an approved plan.
