workflows:brainstorm

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 the question 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, AGENTS.md guidance.

1.2 Collaborative Dialogue

Use the question 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 the question 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 the question tool to present next steps:

Question: “Brainstorm captured. What would you like to do next?”

Options:

1. Review and refine - Improve the document through structured self-review
2. Proceed to planning - Run /workflows:plan (will auto-detect this brainstorm)
3. 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:

1. Move to planning - Continue to /workflows:plan with this document
2. 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.