Brainstorming Ideas Into Designs

Goal

Transform "vague ideas/requirements" into actionable designs and specifications, producing reusable file artifacts (rather than just staying in chat).

Key requirement: Ask only one question at a time. If a topic is complex, break it into multiple rounds of Q&A—don't throw out a checklist all at once.

Core Process (Must Follow)

0) Check Project Context First (Required When Repo Exists)

Before asking questions, quickly check:

• Key documentation: README.md, docs/, design-system.md (if exists)
• Tech stack and constraints: package.json / Cargo.toml / pyproject.toml etc.
• Structure overview: top-level directories, main modules
• Recent changes: git log -n 10 --oneline (if it's a git repo)

Output a very brief context summary: what you observed + possible constraint points (don't start designing yet).

1) Understand the Idea (One Question at a Time)

Goal is to gather the minimum information set (purpose / constraints / success criteria).

Rules:

• Each message asks 1 question only
• Prefer multiple choice (reduce user's cognitive load), use open questions only when necessary
• Ask direction-determining questions first (goals/success criteria/non-goals), then details

2) Explore Solutions (2-3 Options + Trade-offs)

After you understand the requirements:

• Provide 2-3 options (A/B/C)
• Explain trade-offs for each (complexity/risk/iteration speed/long-term cost)
• Give your recommended option first, then explain why

3) Output Design (200-300 Word Segments + Confirm Each)

When you're confident you understand what needs to be done, start outputting the design spec.

Requirements:

• Output in segments (~200-300 words each)
• Ask for confirmation at the end of each segment: e.g., "Does this look good?"
• Design should at least cover:
  • Architecture and module boundaries
  • Core data flow (input → processing → output)
  • Error handling and edge cases
  • Testing and validation strategy (minimum viable set)

If user disagrees with a segment: go back to questioning/option phase to clarify—don't push forward.

Artifacts and Persistence (Strongly Recommended)

Write Design Document

Prefer writing to run directory (artifact-first):

• run_dir/evidence/YYYY-MM-DD-<topic>-design.md

If there's no run_dir but there is a repo_root:

• Create runs/brainstorm/active/<run_id>/, and write design to evidence/

Note: Writing files is a write operation; if this is the user's project repo, confirm "should I persist to the project?" before writing.

Enter Implementation (Optional)

After design is confirmed, ask one question to let user choose next step:

1. Enter implementation directly (recommend workflow-ship-faster or workflow-feature-shipper)
2. Write implementation plan first (persist as checklist items in run_dir/tasks.md, then wait for confirmation)
3. Need research/code reading first (split to run_dir/evidence/parallel/<task-name>/ and do in parallel)

Key Principles

• One question at a time: Never ask 5 questions in one message
• Multiple choice preferred: Help user respond faster and more effectively
• YAGNI: Actively remove "not needed yet" features from the design
• Incremental validation: Output design in segments, confirm each one