Brainstorming Ideas Into Designs

Overview

Turn rough ideas into a validated design/spec through short, collaborative dialogue.

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.

⚠️ IMPORTANT: This skill produces a design document only. Implementation is a separate step that the user decides when and how to do.

The Process

Understand the idea

• •Review current project state first (files, docs, recent commits, existing patterns)
• •Ask one question per message; if a topic needs more exploration, split it across multiple turns
• •Prefer multiple-choice questions when practical (faster to answer), but use open-ended when needed
• •Focus on purpose, constraints, success criteria, and non-goals

Interactive Questions with ask_questions Tool

MUST Use the ask_questions tool for a more interactive and efficient dialogue. This provides a native UI for the user to select options or input text.

Tool Parameters

Rules

• •Maximum 4 questions per call (batch related questions)
• •"Other" option is added automatically — don't add it manually
• •Use recommended only to suggest YOUR preferred implementation choice
• •Omit options array for free text input

Example: Multiple Choice

{
  "questions": [{
    "header": "Approach",
    "question": "Which architecture approach should we use?",
    "options": [
      {"label": "Monolith", "description": "Simple, single deployment"},
      {"label": "Microservices", "description": "Scalable, complex"},
      {"label": "Modular Monolith", "description": "Best of both", "recommended": true}
    ]
  }]
}

Example: Open-Ended

{
  "questions": [{
    "header": "Goal",
    "question": "What is the main goal of this feature?",
    "allowFreeformInput": true
  }]
}

Example: Batched Questions

{
  "questions": [
    {
      "header": "Priority",
      "question": "What's the priority for this feature?",
      "options": [
        {"label": "High - needed this sprint"},
        {"label": "Medium - next sprint"},
        {"label": "Low - backlog"}
      ]
    },
    {
      "header": "Scope",
      "question": "Should we include admin features?",
      "options": [
        {"label": "Yes, full admin panel"},
        {"label": "Yes, basic controls only"},
        {"label": "No, user-facing only", "recommended": true}
      ]
    }
  ]
}

Fallback: Markdown Questions

When the tool is unavailable or for documentation, use this markdown format:

Template (multiple-choice)

**Question: <short title>**
<One-sentence context. **Optional**>

**Choose one:**
**A)** <option>
**B)** <option>
...

**Reply with:** A / B / ...

Explore approaches

• •Propose 2-3 different approaches with trade-offs
• •Lead with your recommended option and explain why
• •Keep options meaningfully different (not tiny variants)

Present the design

• •Present in sections of ~200-300 words
• •After each section, ask if it looks right so far before continuing
• •Cover: architecture, components, data flow, error handling, testing, and rollout (if relevant)

Output: Design Document (MANDATORY)

This step is NOT optional. Every brainstorming session MUST produce a written design document.

1. •

   Write the design document:

   • •Save to docs/plans/YYYY-MM-DD-<topic>-design.md
   • •If docs/plans/ doesn't exist, create it or ask user for preferred location
   • •Include: objective, architecture, specifications from each section, success criteria
2. •

   Document structure:

   markdown

   # <Topic> Design
   
   **Date:** YYYY-MM-DD
   **Status:** Validated
   
   ## Objective
   [What we're building and why]
   
   ## Architecture / Approach
   [Chosen approach with rationale]
   
   ## Specifications
   [Details from each design section]
   
   ## Implementation Order
   [Recommended sequence of tasks]
   
   ## Success Criteria
   - [ ] Criterion 1
   - [ ] Criterion 2
   

3. •

   Confirm with user: "Design saved to docs/plans/.... Ready for implementation?"

After the Design: Implementation (USER'S CHOICE)

Implementation is optional and at user's discretion. Do NOT start implementing unless explicitly asked.

When user wants to implement, recommend these approaches:

If user asks to implement:

1. •Use ask_questions:
   json

   {
     "questions": [{
       "header": "Tracking",
       "question": "How would you like to track implementation?",
       "options": [
         {"label": "Create bd tasks", "description": "For task tracking and team visibility"},
         {"label": "Create GitHub issues", "description": "Standard GitHub workflow"},
         {"label": "Delegate to subagents", "description": "Quick, direct implementation"},
         {"label": "I'll handle it manually"}
       ]
     }]
   }
   

2. •Follow their choice
3. •Do NOT implement yourself unless explicitly delegated

Before making changes:

• •If the repo uses branching/worktrees, create an isolated workspace before making changes
• •Produce an implementation plan with clear, verifiable tasks and checkpoints
• •Each task should have explicit success criteria that can be verified

Key Principles

• •Use ask_questions tool for interactive, efficient dialogue
• •One question at a time (or batch up to 4 related questions)
• •Multiple choice preferred when it doesn't reduce clarity
• •YAGNI ruthlessly (delete unnecessary scope)
• •Explore alternatives before committing
• •Incremental validation (design in sections)
• •Be flexible (backtrack and clarify when needed)
• •Always document — no design lives only in chat
• •Never auto-implement — design and implementation are separate concerns