--- 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--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.