| name | brainstorming |
| description | Expert Socratic discovery skill for exploring ideas, architecture decisions, and technical design before writing any code. Use this skill — proactively and always first — when requirements are vague, when the user is debating between technical approaches, when the problem is unclear, or when a design decision could have significant architectural consequences. Triggers on: "should we use X or Y", "help me think through", "I'm not sure how to approach this", "what's the best architecture for", "trade-offs between", "design before I code", "let's think through this", "I have an idea", "how should I structure", "help me design", "I want to build X but not sure how", "what approach would you recommend", "is this the right way to". Produces a validated design doc with 2-3 implementation options, trade-offs, and a recommendation. Always use before planning when the approach is not yet locked.
|
Brainstorming — Socratic Design Discovery
Why This Matters
The most expensive code to write is the wrong code. Brainstorming exists to prevent that by forcing clarity on purpose, constraints, and design before any implementation begins. A 20-minute brainstorm saves hours of refactoring.
The Socratic method works here because users often don't know what they want — they know what they're trying to achieve. Your job is to ask questions that surface the real requirements hiding behind the initial idea.
When to Use
- Requirements are vague or high-level ("I want to build X")
- The user is debating between technical approaches
- Architecture decisions have long-term consequences
- The feature touches multiple systems or has unclear boundaries
- A new idea needs reality-checking before investing in it
Workflow
1. Context Loading First
Read relevant files, recent commits, and existing docs before asking a single question. Users find it frustrating to explain context that's already in the codebase. The goal is to arrive at the first question already informed.
2. Socratic Discovery
Ask one question at a time. Each question should unlock the next. Good questions:
- Surface constraints the user hasn't articulated yet ("What happens if X fails?")
- Force a choice between concrete options ("Do you want A — faster to ship but harder to change later — or B — more setup but more flexible?")
- Test assumptions ("Are you sure users will actually do Y?")
Prefer multiple-choice questions over open-ended ones. "Do you prefer A or B?" gets faster, more reliable answers than "How should we handle this?"
3. Optioneering
Once you understand the problem well enough, propose 2-3 distinct approaches with explicit trade-offs. Don't hedge — lead with your recommendation and explain why.
Option A (Recommended): [description]
- Pros: [2-3 concrete benefits]
- Cons: [honest limitations]
- Best when: [specific context where this wins]
Option B: [description]
- Pros: [2-3 concrete benefits]
- Cons: [honest limitations]
- Best when: [specific context where this wins]
Option C: [description]
- [same format]
4. Design Verification
Present the design in small chunks (200-300 words each). After each chunk, check: "Does this look right so far?" Don't move to the next section until the current one is approved.
Cover in order:
- Architecture overview
- Key components and their responsibilities
- Data flow between components
- Error handling strategy
- Testing approach
5. Output
Save the validated design to docs/designs/YYYY-MM-DD-<topic>.md. Once the design is locked, suggest moving to the planning skill for atomic task breakdown.
What Good Looks Like
A completed brainstorm leaves the user with:
- A clear answer to "what are we building and why this approach"
- 2-3 rejected alternatives and why they were rejected (this is as valuable as the choice made)
- No ambiguity about the boundaries of the feature
- A design doc they could hand to another engineer
References
references/socratic-questions.md — Question bank organized by problem type (architecture, data model, API design, UI/UX, performance)references/architecture-patterns.md — Common trade-off frameworks (monolith vs microservices, sync vs async, SQL vs NoSQL, client-side vs server-side)
Read the relevant reference file when you need deeper question frameworks or trade-off analysis for a specific domain.
