Skill 011

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

| Parameter | Description | |-----------|-------------| | header | Short label (max 12 chars) - used as identifier | | question | Full question text to display | | options | Array of 0-6 options with label and optional description | | multiSelect | Allow multiple selections (default: false) | | allowFreeformInput | Allow free text in addition to options | | recommended | Mark an option as recommended (never use for quizzes) |

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:

Choose one: A) B) ...

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--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

1. Document structure:

```markdown # 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

```

1. 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:

| Approach | When to use | How | |----------|-------------|-----| | bd (beads) | Task tracking, team visibility | bd create "" for each item in Implementation Order | | PRD | Complex features, stakeholder alignment | Create docs/prd/YYYY-MM-DD-.md with full requirements | | Direct tasks | Simple, quick implementations | Use task-delegation skill to delegate to subagents | | Issues | GitHub/GitLab workflow | Create issues from Implementation Order |

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"} ] }] } ``

1. Follow their choice
2. 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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: legendtkl
• Source: legendtkl/agentic-skill-router
• License: MIT
• Homepage: https://legendtkl.github.io/agentic-skill-router/

Install and usage instructions live in the source repository linked above.