a5bba3dc54
Add optional review and refine step to workflows:brainstorm and workflows:plan that checks documents for clarity, completeness, user intent, and YAGNI. - New document-review skill with review questions and evaluation criteria - Brainstorm Phase 4 offers "Review and refine" option - Plan post-generation offers "Review and refine" after technical review - Includes YAGNI-based simplification guidance - Max 2 iteration rounds before suggesting to proceed Co-authored-by: Kieran Klaassen <kieranklaassen@users.noreply.github.com>
4.1 KiB
name, description, argument-hint
| name | description | argument-hint |
|---|---|---|
| workflows:brainstorm | Explore requirements and approaches through collaborative dialogue before planning implementation | [feature idea or problem to explore] |
Brainstorm a Feature or Improvement
Note: The current year is 2026. Use this when dating brainstorm documents.
Brainstorming helps answer WHAT to build through collaborative dialogue. It precedes /workflows:plan, which answers HOW to build it.
Process knowledge: Load the brainstorming skill for detailed question techniques, approach exploration patterns, and YAGNI principles.
Feature Description
<feature_description> #$ARGUMENTS </feature_description>
If the feature description above is empty, ask the user: "What would you like to explore? Please describe the feature, problem, or improvement you're thinking about."
Do not proceed until you have a feature description from the user.
Execution Flow
Phase 0: Assess Requirements Clarity
Evaluate whether brainstorming is needed based on the feature description.
Clear requirements indicators:
- Specific acceptance criteria provided
- Referenced existing patterns to follow
- Described exact expected behavior
- Constrained, well-defined scope
If requirements are already clear:
Use AskUserQuestion tool to suggest: "Your requirements seem detailed enough to proceed directly to planning. Should I run /workflows:plan instead, or would you like to explore the idea further?"
Phase 1: Understand the Idea
1.1 Repository Research (Lightweight)
Run a quick repo scan to understand existing patterns:
- Task repo-research-analyst("Understand existing patterns related to: <feature_description>")
Focus on: similar features, established patterns, CLAUDE.md guidance.
1.2 Collaborative Dialogue
Use the AskUserQuestion tool to ask questions one at a time.
Guidelines (see brainstorming skill for detailed techniques):
- Prefer multiple choice when natural options exist
- Start broad (purpose, users) then narrow (constraints, edge cases)
- Validate assumptions explicitly
- Ask about success criteria
Exit condition: Continue until the idea is clear OR user says "proceed"
Phase 2: Explore Approaches
Propose 2-3 concrete approaches based on research and conversation.
For each approach, provide:
- Brief description (2-3 sentences)
- Pros and cons
- When it's best suited
Lead with your recommendation and explain why. Apply YAGNI—prefer simpler solutions.
Use AskUserQuestion tool to ask which approach the user prefers.
Phase 3: Capture the Design
Write a brainstorm document to docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md.
Document structure: See the brainstorming skill for the template format. Key sections: What We're Building, Why This Approach, Key Decisions, Open Questions.
Ensure docs/brainstorms/ directory exists before writing.
Phase 4: Handoff
Use AskUserQuestion tool to present next steps:
Question: "Brainstorm captured. What would you like to do next?"
Options:
- Review and refine - Improve the document through structured self-review
- Proceed to planning - Run
/workflows:plan(will auto-detect this brainstorm) - Done for now - Return later
If user selects "Review and refine":
Load the document-review skill and apply it to the brainstorm document.
When document-review returns "Review complete", present next steps:
- Move to planning - Continue to
/workflows:planwith this document - Done for now - Brainstorming complete. To start planning later:
/workflows:plan [document-path]
Output Summary
When complete, display:
Brainstorm complete!
Document: docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md
Key decisions:
- [Decision 1]
- [Decision 2]
Next: Run `/workflows:plan` when ready to implement.
Important Guidelines
- Stay focused on WHAT, not HOW - Implementation details belong in the plan
- Ask one question at a time - Don't overwhelm
- Apply YAGNI - Prefer simpler approaches
- Keep outputs concise - 200-300 words per section max
NEVER CODE! Just explore and document decisions.