136 lines
8.2 KiB
Markdown
136 lines
8.2 KiB
Markdown
---
|
||
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.
|