tools-only Brainstorming
Provides guided brainstorming to transform ideas into fully formed designs with professional documentation and next-step recommendations.
Overview
This command helps developers transform an initial idea into a comprehensive, validated design through a systematic 9-phase process:
- Context Discovery - Understand the project state and initial idea
- Idea Refinement - Deeply understand requirements through structured dialogue
- Approach Exploration - Present 2-3 approaches with trade-offs
- Codebase Exploration - Analyze existing code for design constraints
- Design Presentation - Present validated design sections incrementally
- Documentation Generation - Generate professional design documents
- Document Review - Quality review by specialist agent
- Next Steps Recommendation - Suggest appropriate next command
- Summary - Document what was accomplished
Use this command when starting a new feature, exploring design alternatives, or planning significant changes.
Usage
/developer-kit:devkit.brainstorm [idea-description]
Arguments
| Argument | Required | Description |
|---|---|---|
idea-description |
No | Description of the idea or feature to brainstorm |
Current Context
The command will automatically gather context information when needed:
- Current git branch and status
- Recent commits and changes
- Available when the repository has history
Argument Details
idea-description
- Purpose: Describes the initial idea, feature, or problem to solve
- Format: Free text describing the concept
- Default: If not provided, the command will ask for it interactively
- Examples: "Add user authentication", "Refactor payment module", "Design caching strategy"
You are helping a developer transform an idea into a fully formed design. Follow a systematic approach: understand the project context, explore the idea through targeted questions, explore existing code, propose alternative approaches, present the design incrementally, generate professional documentation, review the document, and recommend the next development command.
Core Principles
- 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 with trade-offs
- Incremental validation: Present design in sections, validate each
- Code-based design: Base design decisions on actual codebase exploration
- Professional documentation: Use specialist agent for high-quality documents
- Be flexible: Go back and clarify when something doesn't make sense
- Use TodoWrite: Track all progress throughout
- No time estimates: DO NOT provide or request time estimates
Phase 1: Context Discovery
Goal: Understand the current project state and the initial idea
Initial idea: $ARGUMENTS
Actions:
- Create todo list with all phases
- Explore the current project state:
- Read recent commits to understand what's being worked on
- Check for existing documentation (README, docs/, existing plans)
- Identify the technology stack and architecture patterns
- Look for related features or similar implementations
- If the idea is unclear, ask the user for:
- What problem are they trying to solve?
- What is the high-level goal?
- Any initial thoughts or constraints?
Phase 2: Idea Refinement
Goal: Deeply understand the idea through structured dialogue
CRITICAL: This phase builds the foundation for the design. DO NOT rush.
Actions:
- Ask questions one at a time to refine the idea
- Use the AskUserQuestion tool with multiple choice options when possible
- Focus on understanding:
- Purpose: What is this trying to achieve?
- Constraints: Are there technical, time, or resource constraints?
- Success Criteria: How will we know if this is successful?
- Scope: What is in scope and what is explicitly out of scope?
- Users: Who will use this and how?
Example structured questions:
- "What is the primary success metric for this feature?"
- "Which constraint is most important: development time, performance, or maintainability?"
- "Who are the primary users of this feature?"
- Wait for each answer before asking the next question
- When the idea is clear, summarize understanding and get confirmation
Phase 3: Approach Exploration
Goal: Present 2-3 different approaches with trade-offs
Actions:
Based on the refined idea, develop 2-3 distinct approaches:
- Approach A: Simple/MVP (fastest to implement, may lack some features)
- Approach B: Balanced (good feature set, reasonable complexity) - typically your recommendation
- Approach C: Comprehensive (full-featured, more complex)
For each approach, describe:
- High-level architecture
- Key components
- Pros (benefits, advantages)
- Cons (drawbacks, risks)
- Estimated complexity
Use the AskUserQuestion tool to present the approaches:
- Lead with your recommended option
- Explain your reasoning
- Ask which approach they prefer
Wait for user selection before proceeding
Phase 4: Codebase Exploration
Goal: Deep understanding of existing codebase before finalizing the design
CRITICAL: This phase ensures the design is based on actual codebase reality, not assumptions.
Actions:
- Use the Task tool to launch a code-explorer subagent to analyze the existing codebase:
Task(
description: "Explore codebase for design context",
prompt: "Explore the codebase comprehensively to support the following design: [design summary]
Focus on:
1. Existing patterns and conventions used in similar features
2. Architecture layers and module organization
3. Key integration points and dependencies
4. Data models and persistence patterns
5. API design patterns (if applicable)
6. Testing patterns and infrastructure
7. Configuration and environment setup
8. Any potential conflicts or integration challenges
Return:
- List of key files to read for deep understanding
- Summary of relevant patterns found
- Any recommendations or considerations for the design",
subagent_type: "developer-kit:general-code-explorer"
)
- Once the agent returns, read all identified critical files
- Incorporate findings into the design understanding
- If significant new information is discovered that affects the design:
- Use the AskUserQuestion tool to discuss with the user
- Potentially revisit Phase 3 (Approach Exploration) if needed
Phase 5: Design Presentation
Goal: Present the approved design in validated sections
DO NOT START WITHOUT APPROACH APPROVAL
Actions:
Once the approach is selected and codebase is explored, present the design in sections of 200-300 words each
Incorporate findings from Phase 4 (Codebase Exploration) into the design
Cover the following areas in separate sections:
Section 1: Architecture Overview
- System architecture and how it fits into existing codebase
- Key architectural patterns and principles (based on actual patterns found)
- Integration points with existing systems
Section 2: Components and Modules
- Main components or classes involved
- Responsibilities of each component
- Relationships between components
- Alignment with existing module structure
Section 3: Data Flow
- How data flows through the system
- Key data structures
- State management considerations
Section 4: Error Handling
- Expected failure scenarios
- Error handling strategy
- User-facing error messages vs. internal errors
Section 5: Testing Strategy
- Key test scenarios
- Testing approach (unit, integration, e2e)
- Edge cases to consider
After each section, use the AskUserQuestion tool:
- "Does this section look right so far?"
- Options: "Yes, continue", "Needs revision", "Go back to earlier section"
Wait for validation before proceeding to the next section
Phase 6: Documentation Generation
Goal: Generate professional documentation using the document generator specialist
Actions:
- Compile all validated design sections into a comprehensive design brief
- Use the Task tool to launch the document-generator-expert subagent:
Task(
description: "Generate design document",
prompt: "Generate a professional design document based on the following validated design:
**Design Title**: [title]
**Date**: [current date]
**Overview**: [brief summary]
**Requirements**:
- Functional: [list]
- Non-Functional: [list]
- Success Criteria: [list]
**Approach Selected**: [name with rationale]
**Architecture**: [from Section 1]
**Components**: [from Section 2]
**Data Flow**: [from Section 3]
**Error Handling**: [from Section 4]
**Testing Strategy**: [from Section 5]
**Out of Scope**: [list]
**Open Questions**: [list]
Create a comprehensive, well-formatted design document and save it to: docs/plans/YYYY-MM-DD--design.md
The document should be:
- Professional and clearly formatted
- DO NOT provide or request time estimates or implementation timelines
- Complete with all sections
- Ready for team review
- Using proper markdown structure",
subagent_type: "developer-kit:document-generator-expert"
)
- Wait for the document generator to complete
- Verify the document was created successfully
- Update todos
Phase 7: Document Review
Goal: Review the generated document for quality and completeness using specialist agent
Actions:
- Use the Task tool to launch a code-reviewer subagent to review the document:
Task(
description: "Review design document quality",
prompt: "Review the design document at docs/plans/YYYY-MM-DD--design.md for:
1. **Completeness**: All required sections are present (Overview, Requirements, Approach Selected, Architecture, Components, Data Flow, Error Handling, Testing Strategy, Out of Scope, Open Questions)
2. **Quality**: Content is clear, specific, and actionable
3. **Alignment**: Document matches the validated design from the brainstorming session:
- Architecture overview is consistent with codebase patterns
- Components and modules are properly defined
- Data flow is logical and complete
- Error handling covers edge cases
- Testing strategy is comprehensive
4. **Formatting**: Proper markdown structure, consistent formatting
5. **Clarity**: Language is professional, concise, and unambiguous
Provide:
- Overall assessment (Excellent / Good / Needs Revision)
- List of any missing sections or content
- Specific issues found (if any)
- Recommendations for improvement (if needed)",
subagent_type: "developer-kit:general-code-reviewer"
)
Once the agent returns, synthesize the review findings
Use the AskUserQuestion tool to present the review findings:
Present options based on agent assessment:
- Option A: Document is excellent, proceed to next steps
- Option B: Minor revisions needed (agent will specify what)
- Option C: Major revisions needed (regenerate with corrections)
If revisions are needed:
- For minor revisions: Edit the document directly based on agent feedback
- For major revisions: Re-run Phase 6 with updated instructions from agent
- Optionally: Re-run Phase 7 with another review if significant changes were made
Once approved, mark documentation phase complete
Phase 8: Next Steps Recommendation
Goal: Recommend the appropriate next development command
Actions:
Analyze the design to determine the best next step:
For new features: Recommend
/developer-kit:devkit.feature-development- Use when: Creating new functionality, adding features, implementing the design from scratch
- Arguments: Provide a concise summary of the feature description
For fixing issues: Recommend
/developer-kit:devkit.fix-debugging- Use when: The design addresses a bug, error, or production issue
- Arguments: Provide the issue description or error message
For improving code: Recommend
/developer-kit:devkit.refactor- Use when: The design involves restructuring, reorganizing, or improving existing code
- Arguments: Provide the refactoring description
Use the AskUserQuestion tool to present the recommendation:
Present options:
- Option A: [Recommended command] with pre-filled arguments
- Option B: Choose a different command manually
- Option C: Exit and review the design document first
Include the pre-filled command that can be copied/pasted:
# Example for feature development
/developer-kit:devkit.feature-development [concise feature description based on design]
# Example for debugging
/developer-kit:devkit.fix-debugging [issue description based on design]
# Example for refactoring
/developer-kit:devkit.refactor [refactoring description based on design]
- If user chooses to continue, remind them:
- The design document has been saved at
docs/plans/YYYY-MM-DD--design.md - They can reference this during implementation
- The design document has been saved at
Phase 9: Summary
Goal: Document what was accomplished
Actions:
- Mark all todos complete
- Summarize:
- Original Idea: What was brainstormed
- Approach Selected: Which approach was chosen and why
- Codebase Analysis: Key findings from codebase exploration
- Design Created: Key aspects of the design
- Document Location:
docs/plans/YYYY-MM-DD--design.md - Document Review: Review outcome and any revisions made
- Recommended Next Step: The suggested command with arguments
- Alternative Paths: Other commands that could be used if priorities change
Practical Examples
# Simple feature idea
/developer-kit:devkit.brainstorm Add user authentication with JWT tokens
# Complex feature idea
/developer-kit:devkit.brainstorm Implement real-time notifications using WebSockets
# Refactoring idea
/developer-kit:devkit.brainstorm Refactor the payment processing module to be more maintainable
# Bug fix design
/developer-kit:devkit.brainstorm Design a fix for the race condition in order processing
# Performance improvement
/developer-kit:devkit.brainstorm Design a caching strategy to reduce API response times
# Integration idea
/developer-kit:devkit.brainstorm Integrate Stripe payment processing for subscriptions
# Architecture idea
/developer-kit:devkit.brainstorm Design a microservices architecture for the reporting module
Integration with Development Commands
This brainstorming command is designed to feed directly into the development workflow:
Output Flow
/developer-kit:devkit.brainstorm
↓
Phase 4: Codebase Exploration (code-explorer agent)
↓
Phase 5: Design Presentation (validated incrementally)
↓
Phase 6: Documentation (document-generator-expert agent)
↓
Phase 7: Document Review (quality verification)
↓
[Creates: docs/plans/YYYY-MM-DD--design.md]
↓
[Recommends next command with pre-filled arguments]
↓
User executes recommended command:
- /developer-kit:devkit.feature-development [description]
- /developer-kit:devkit.fix-debugging [description]
- /developer-kit:devkit.refactor [description]
Design Document as Reference
The design document created by this command serves as:
- Reference during implementation: The development commands can read the design document for context
- Communication tool: Can be shared with team members for review
- Documentation: Becomes part of the project's design history
- Testing guide: The testing strategy section informs test creation
Re-entering Brainstorming
If implementation reveals design issues, you can re-run /developer-kit:devkit.brainstorm with the revised idea:
- The previous design document will be preserved
- A new design document will be created with the current date
- You can reference the previous design during the new brainstorming session
Todo Management
Throughout the process, maintain a todo list like:
[ ] Phase 1: Context Discovery
[ ] Phase 2: Idea Refinement
[ ] Phase 3: Approach Exploration
[ ] Phase 4: Codebase Exploration
[ ] Phase 5: Design Presentation
[ ] Section 1: Architecture Overview
[ ] Section 2: Components and Modules
[ ] Section 3: Data Flow
[ ] Section 4: Error Handling
[ ] Section 5: Testing Strategy
[ ] Phase 6: Documentation Generation
[ ] Phase 7: Document Review
[ ] Phase 8: Next Steps Recommendation
[ ] Phase 9: Summary
Update the status as you progress through each phase and section.
Note: This command follows a collaborative, iterative approach with specialist agents to ensure designs are:
- Based on actual codebase exploration (not assumptions)
- Well-thought-out and validated incrementally
- Documented professionally with specialist assistance
- Reviewed for quality before proceeding
- Ready for implementation with clear next steps
Examples
Example 1: Simple Feature Idea
/developer-kit:devkit.brainstorm Add user authentication with JWT tokens
Example 2: Complex Feature
/developer-kit:devkit.brainstorm Implement real-time notifications using WebSockets
Example 3: Refactoring
/developer-kit:devkit.brainstorm Refactor the payment processing module to be more maintainable