|
|
@@ -1,175 +1,54 @@
|
|
|
---
|
|
|
name: brainstorming
|
|
|
-description: Use when creating or developing anything, before writing code or implementation plans - refines rough ideas into fully-formed designs through structured Socratic questioning, alternative exploration, and incremental validation
|
|
|
+description: Use when creating or developing, before writing code or implementation plans - refines rough ideas into fully-formed designs through collaborative questioning, alternative exploration, and incremental validation. Don't use during clear 'mechanical' processes
|
|
|
---
|
|
|
|
|
|
# Brainstorming Ideas Into Designs
|
|
|
|
|
|
## Overview
|
|
|
|
|
|
-Transform rough ideas into fully-formed designs through structured questioning and alternative exploration.
|
|
|
+Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
|
|
|
|
|
|
-**Core principle:** Research first, ask targeted questions to fill gaps, explore alternatives, present design incrementally for validation.
|
|
|
-
|
|
|
-**Announce at start:** "I'm using the brainstorming skill to refine your idea into a design."
|
|
|
-
|
|
|
-## Quick Reference
|
|
|
-
|
|
|
-| Phase | Key Activities | Tool Usage | Output |
|
|
|
-|-------|---------------|------------|--------|
|
|
|
-| **Prep: Autonomous Recon** | Inspect repo/docs/commits, form initial model | Native tools (ls, cat, git log, etc.) | Draft understanding to confirm |
|
|
|
-| **1. Understanding** | Share findings, ask only for missing context | AskUserQuestion for real decisions | Purpose, constraints, criteria (confirmed) |
|
|
|
-| **2. Exploration** | Propose 2-3 approaches | AskUserQuestion for approach selection | Architecture options with trade-offs |
|
|
|
-| **3. Design Presentation** | Present in 200-300 word sections | Open-ended questions | Complete design with validation |
|
|
|
-| **4. Design Documentation** | Write design document | writing-clearly-and-concisely skill | Design doc in docs/plans/ |
|
|
|
-| **5. Worktree Setup** | Set up isolated workspace | using-git-worktrees skill | Ready development environment |
|
|
|
-| **6. Planning Handoff** | Create implementation plan | writing-plans skill | Detailed task breakdown |
|
|
|
+Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design in small sections (200-300 words), checking after each section whether it looks right so far.
|
|
|
|
|
|
## The Process
|
|
|
|
|
|
-Copy this checklist to track progress:
|
|
|
-
|
|
|
-```
|
|
|
-Brainstorming Progress:
|
|
|
-- [ ] Prep: Autonomous Recon (repo/docs/commits reviewed, initial model shared)
|
|
|
-- [ ] Phase 1: Understanding (purpose, constraints, criteria gathered)
|
|
|
-- [ ] Phase 2: Exploration (2-3 approaches proposed and evaluated)
|
|
|
-- [ ] Phase 3: Design Presentation (design validated in sections)
|
|
|
-- [ ] Phase 4: Design Documentation (design written to docs/plans/)
|
|
|
-- [ ] Phase 5: Worktree Setup (if implementing)
|
|
|
-- [ ] Phase 6: Planning Handoff (if implementing)
|
|
|
-```
|
|
|
-
|
|
|
-### Prep: Autonomous Recon
|
|
|
-- Use existing tools (file browsing, docs, git history, tests) to understand current project state before asking anything.
|
|
|
-- Form your draft model: what problem you're solving, what artifacts exist, and what questions remain.
|
|
|
-- Start the conversation by sharing that model: "Based on exploring the project state, docs, working copy, and recent commits, here's how I think this should work…"
|
|
|
-- Ask follow-up questions only for information you cannot infer from available materials.
|
|
|
-
|
|
|
-### Phase 1: Understanding
|
|
|
-- Share your synthesized understanding first, then invite corrections or additions.
|
|
|
-- Ask one focused question at a time, only for gaps you cannot close yourself.
|
|
|
-- **Use AskUserQuestion tool** only when you need the human to make a decision among real alternatives.
|
|
|
-- Gather: Purpose, constraints, success criteria (confirmed or amended by your partner)
|
|
|
-
|
|
|
-**Example summary + targeted question:**
|
|
|
-```
|
|
|
-Based on the README and yesterday's commit, we're expanding localization to dashboard and billing emails; admin console is still untouched. Only gap I see is whether support responses need localization in this iteration. Did I miss anything important?
|
|
|
-```
|
|
|
-
|
|
|
-### Phase 2: Exploration
|
|
|
-- Propose 2-3 different approaches
|
|
|
-- For each: Core architecture, trade-offs, complexity assessment, and your recommendation
|
|
|
-- **Use AskUserQuestion tool** to present approaches when you truly need a judgement call
|
|
|
-- Lead with the option you prefer and explain why; invite disagreement if your partner sees it differently
|
|
|
-- Own prioritization: if the repo makes priorities clear, state them and proceed rather than asking
|
|
|
-
|
|
|
-**Example using AskUserQuestion:**
|
|
|
-```
|
|
|
-Question: "Which architectural approach should we use?"
|
|
|
-Options:
|
|
|
- - "Direct API calls with retry logic" (simple, synchronous, easier to debug) ← recommended for current scope
|
|
|
- - "Event-driven with message queue" (scalable, complex setup, eventual consistency)
|
|
|
- - "Hybrid with background jobs" (balanced, moderate complexity, best of both)
|
|
|
-
|
|
|
-I recommend the direct API approach because it matches existing patterns and minimizes new infrastructure. Let me know if you see a blocker that pushes us toward the other options.
|
|
|
-```
|
|
|
-
|
|
|
-### Phase 3: Design Presentation
|
|
|
-- Present in coherent sections; use ~200-300 words when introducing new material, shorter summaries once alignment is obvious
|
|
|
-- Cover: Architecture, components, data flow, error handling, testing
|
|
|
-- Check in at natural breakpoints rather than after every paragraph: "Stop me if this diverges from what you expect."
|
|
|
-- Use open-ended questions to allow freeform feedback
|
|
|
-- Assume ownership and proceed unless your partner redirects you
|
|
|
-
|
|
|
-### Phase 4: Design Documentation
|
|
|
-After validating the design, write it to a permanent document:
|
|
|
-- **File location:** `docs/plans/YYYY-MM-DD-<topic>-design.md` (use actual date and descriptive topic)
|
|
|
-- **RECOMMENDED SUB-SKILL:** Use elements-of-style:writing-clearly-and-concisely (if available) for documentation quality
|
|
|
-- **Content:** Capture the design as discussed and validated in Phase 3, organized into sections that emerged from the conversation
|
|
|
-- Commit the design document to git before proceeding
|
|
|
-
|
|
|
-### Phase 5: Worktree Setup (for implementation)
|
|
|
-When design is approved and implementation will follow:
|
|
|
-- Announce: "I'm using the using-git-worktrees skill to set up an isolated workspace."
|
|
|
-- **REQUIRED SUB-SKILL:** Use superpowers:using-git-worktrees
|
|
|
-- Follow that skill's process for directory selection, safety verification, and setup
|
|
|
-- Return here when worktree ready
|
|
|
-
|
|
|
-### Phase 6: Planning Handoff
|
|
|
-Ask: "Ready to create the implementation plan?"
|
|
|
-
|
|
|
-When your human partner confirms (any affirmative response):
|
|
|
-- Announce: "I'm using the writing-plans skill to create the implementation plan."
|
|
|
-- **REQUIRED SUB-SKILL:** Use superpowers:writing-plans
|
|
|
-- Create detailed plan in the worktree
|
|
|
-
|
|
|
-## Question Patterns
|
|
|
-
|
|
|
-### When to Use AskUserQuestion Tool
|
|
|
-
|
|
|
-**Use AskUserQuestion when:**
|
|
|
-- You need your partner to make a judgement call among real alternatives
|
|
|
-- You have a recommendation and can explain why it’s your preference
|
|
|
-- Prioritization is ambiguous and cannot be inferred from existing materials
|
|
|
-
|
|
|
-**Best practices:**
|
|
|
-- State your preferred option and rationale inside the question so your partner can agree or redirect
|
|
|
-- If you know the answer from repo/docs, state it as fact and proceed—no question needed
|
|
|
-- When priorities are spelled out, acknowledge them and proceed rather than delegating the choice back to your partner
|
|
|
-
|
|
|
-### When to Use Open-Ended Questions
|
|
|
-
|
|
|
-**Use open-ended questions for:**
|
|
|
-- Phase 3: Design validation ("Does this look right so far?")
|
|
|
-- When you need detailed feedback or explanation
|
|
|
-- When partner should describe their own requirements
|
|
|
-- When structured options would limit creative input
|
|
|
-
|
|
|
-Frame them to confirm or expand your current understanding rather than reopening settled topics.
|
|
|
-
|
|
|
-**Example decision flow:**
|
|
|
-- "What authentication method?" → Use AskUserQuestion (2-4 options)
|
|
|
-- "Does this design handle your use case?" → Open-ended (validation)
|
|
|
-
|
|
|
-## When to Revisit Earlier Phases
|
|
|
-
|
|
|
-```dot
|
|
|
-digraph revisit_phases {
|
|
|
- rankdir=LR;
|
|
|
- "New constraint revealed?" [shape=diamond];
|
|
|
- "Partner questions approach?" [shape=diamond];
|
|
|
- "Requirements unclear?" [shape=diamond];
|
|
|
- "Return to Phase 1" [shape=box, style=filled, fillcolor="#ffcccc"];
|
|
|
- "Return to Phase 2" [shape=box, style=filled, fillcolor="#ffffcc"];
|
|
|
- "Continue forward" [shape=box, style=filled, fillcolor="#ccffcc"];
|
|
|
-
|
|
|
- "New constraint revealed?" -> "Return to Phase 1" [label="yes"];
|
|
|
- "New constraint revealed?" -> "Partner questions approach?" [label="no"];
|
|
|
- "Partner questions approach?" -> "Return to Phase 2" [label="yes"];
|
|
|
- "Partner questions approach?" -> "Requirements unclear?" [label="no"];
|
|
|
- "Requirements unclear?" -> "Return to Phase 1" [label="yes"];
|
|
|
- "Requirements unclear?" -> "Continue forward" [label="no"];
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-**You can and should go backward when:**
|
|
|
-- Partner reveals new constraint during Phase 2 or 3 → Return to Phase 1
|
|
|
-- Validation shows fundamental gap in requirements → Return to Phase 1
|
|
|
-- Partner questions approach during Phase 3 → Return to Phase 2
|
|
|
-- Something doesn't make sense → Go back and clarify
|
|
|
-
|
|
|
-**Avoid forcing forward linearly** when going backward would give better results.
|
|
|
+**Understanding the idea:**
|
|
|
+- Check out the current project state first (files, docs, recent commits)
|
|
|
+- Ask questions one at a time to refine the idea
|
|
|
+- Prefer multiple choice questions when possible, but open-ended is fine too
|
|
|
+- Only one question per message - if a topic needs more exploration, break it into multiple questions
|
|
|
+- Focus on understanding: purpose, constraints, success criteria
|
|
|
+
|
|
|
+**Exploring approaches:**
|
|
|
+- Propose 2-3 different approaches with trade-offs
|
|
|
+- Present options conversationally with your recommendation and reasoning
|
|
|
+- Lead with your recommended option and explain why
|
|
|
+
|
|
|
+**Presenting the design:**
|
|
|
+- Once you believe you understand what you're building, present the design
|
|
|
+- Break it into sections of 200-300 words
|
|
|
+- Ask after each section whether it looks right so far
|
|
|
+- Cover: architecture, components, data flow, error handling, testing
|
|
|
+- Be ready to go back and clarify if something doesn't make sense
|
|
|
+
|
|
|
+## After the Design
|
|
|
+
|
|
|
+**Documentation:**
|
|
|
+- Write the validated design to `docs/plans/YYYY-MM-DD-<topic>-design.md`
|
|
|
+- Use elements-of-style:writing-clearly-and-concisely skill if available
|
|
|
+- Commit the design document to git
|
|
|
+
|
|
|
+**Implementation (if continuing):**
|
|
|
+- Ask: "Ready to set up for implementation?"
|
|
|
+- Use superpowers:using-git-worktrees to create isolated workspace
|
|
|
+- Use superpowers:writing-plans to create detailed implementation plan
|
|
|
|
|
|
## Key Principles
|
|
|
|
|
|
-| Principle | Application |
|
|
|
-|-----------|-------------|
|
|
|
-| **One question at a time** | Phase 1: Single targeted question only for gaps you can’t close yourself |
|
|
|
-| **Structured choices** | Use AskUserQuestion tool for 2-4 options with trade-offs |
|
|
|
-| **YAGNI ruthlessly** | Remove unnecessary features from all designs |
|
|
|
-| **Explore alternatives** | Always propose 2-3 approaches before settling |
|
|
|
-| **Incremental validation** | Present design in sections, validate each |
|
|
|
-| **Flexible progression** | Go backward when needed - flexibility > rigidity |
|
|
|
-| **Own the initiative** | Recommend priorities and next steps; ask if you should proceed only when requirements conflict |
|
|
|
-| **Announce usage** | State skill usage at start of session |
|
|
|
+- **One question at a time** - Don't overwhelm with multiple questions
|
|
|
+- **Multiple choice preferred** - Easier to answer than open-ended when possible
|
|
|
+- **YAGNI ruthlessly** - Remove unnecessary features from all designs
|
|
|
+- **Explore alternatives** - Always propose 2-3 approaches before settling
|
|
|
+- **Incremental validation** - Present design in sections, validate each
|
|
|
+- **Be flexible** - Go back and clarify when something doesn't make sense
|