brainstorming

Brainstorming Ideas Into Designs

Overview

Help turn ideas into specs and designs through natural collaborative dialogue.

Start by understanding the current project context, then ask questions one at a time to refine the idea. Once clear, research best practices, then formalize requirements (WHAT) before designing solutions (HOW). Present both in small sections, validating as you go.

The Process

Understanding the idea:

• Launch an Explore subagent in the background to identify the current state
• While the Explore subagent is running, ask questions one at a time to refine the idea
• Use AskUserQuestion for choices with clear options (database, auth method, architecture)
• Open-ended questions are fine for "what does success look like?" or exploring unknowns
• Only one question per message - break complex topics into multiple questions
• Focus on understanding: what is being asked, the best approach in delivering

Researching best practices:

Before designing, research to prevent reinventing the wheel and identify pitfalls early.

1. Search using the Explore agent (Task tool with subagent_type=Explore):

   • Current best practices, design patterns, and proven algorithms
   • Libraries or frameworks that solve similar problems
   • Common pitfalls and how others solved them
   • Security considerations if relevant

2. Summarize findings for the user (bullet points):

   • 2-3 patterns or approaches worth considering
   • Libraries/tools to evaluate (with brief rationale)
   • Pitfalls to watch out for

3. Note design impact — does anything change the approach?

4. Ask specifically: "Should we explore [X] vs [Y]?" or "Want to dig deeper into any of these?"

Building the specification (WHAT):

• Once requirements are understood, build a formal spec document incrementally
• Present each section (200-300 words), validate before moving on
• Cover these sections in order:

• Number requirements (FR-001, NFR-001) for traceability
• Each requirement should be testable and unambiguous
• Always include this standing NFR: "All code must compile and pass language-specific linters/type checkers (e.g., tsc, eslint, rustc, go vet, mypy)"
• Save spec to .artifacts/{kebab-style-slug}/YYYY-MM-DD-<topic>-spec.md
• Log out-of-scope items to .artifacts/GDD.md (games) or .artifacts/ROADMAP.md (non-games) so deferred ideas aren't lost

GDD.md template (games):

# [Game Title] - Game Design Document

## Vision
[One-sentence core concept]

## Backlog
| Item | Context | Priority |
|------|---------|----------|
| [Feature] | [Why deferred, what it would involve] | High/Med/Low |

ROADMAP.md template (non-games):

# [Project Name] - Roadmap

## Current Focus
[What we're building now]

## Backlog
| Item | Context | Priority |
|------|---------|----------|
| [Feature] | [Why deferred, what it would involve] | High/Med/Low |

Exploring approaches (HOW):

• Now that requirements are clear, propose 2-3 approaches with trade-offs
• Use AskUserQuestion with recommendation first, trade-offs in descriptions
• Lead with your recommended option and explain why

Presenting the design:

• Once approach is chosen, present the detailed design
• Break it into sections of 200-300 words
• Ask after each section whether it looks right so far
• Cover: architecture, components, data flow, error handling, testing
• Be ready to go back and clarify if something doesn't make sense

Wrapping Up

Documentation:

• Save design to .artifacts/{kebab-style-slug}/YYYY-MM-DD-<topic>-design.md
• Save spec to .artifacts/{kebab-style-slug}/YYYY-MM-DD-<topic>-spec.md
• Commit both documents to git together

Implementation (if continuing):

• Create feature branch: git checkout -b feature/<kebab-style-slug>
• Use harness:writing-plans to create detailed implementation plan
• After plan is saved, start fresh session for implementation

Key Principles

• One question at a time - Don't overwhelm with multiple questions
• Use AskUserQuestion for choices - Clickable options reduce user effort
• Spec before design - Define WHAT before deciding HOW
• YAGNI ruthlessly - Remove unnecessary features from all designs
• Capture deferred items - Log out-of-scope ideas to GDD.md or ROADMAP.md
• Explore alternatives - Always propose 2-3 approaches before settling
• Incremental validation - Present design and spec in sections, validate each
• Be flexible - Go back and clarify when something doesn't make sense