marsai-brainstorming

name	marsai:brainstorming
description	Socratic design refinement - transforms rough ideas into validated designs through structured questioning, alternative exploration, and incremental validation.
trigger	- New feature or product idea (requirements unclear) - User says "plan", "design", or "architect" something - Multiple approaches seem possible - Design hasn't been validated by user
skip_when	- Design already complete and validated → use marsai:writing-plans - Have detailed plan ready to execute → use marsai:executing-plans - Just need task breakdown from existing design → use marsai:writing-plans
sequence	{"before":["marsai:writing-plans","marsai:using-git-worktrees"]}
related	{"similar":["marsai:writing-plans"]}

Brainstorming Ideas Into Designs

Overview

Transform rough ideas into fully-formed designs through structured questioning and alternative exploration.

Core principle: Research first, ask targeted questions to fill gaps, explore alternatives, present design incrementally for validation.

Announce at start: "I'm using the marsai:brainstorming skill to refine your idea into a design."

Quick Reference

Phase	Key Activities	Tool Usage	Output
Prep: Autonomous Recon	Inspect repo/docs/commits, form initial model	Native tools (ls, cat, git log, etc.)	Draft understanding to confirm
1. Understanding	Share findings, ask only for missing context	AskUserQuestion for real decisions	Purpose, constraints, criteria (confirmed)
2. Exploration	Propose 2-3 approaches	AskUserQuestion for approach selection	Architecture options with trade-offs
3. Design Presentation	Present in 200-300 word sections	Open-ended questions	Complete design with validation
4. Design Documentation	Write design document	writing-clearly-and-concisely skill	Design doc in docs/plans/
5. Worktree Setup	Set up isolated workspace	marsai:using-git-worktrees skill	Ready development environment
6. Planning Handoff	Create implementation plan	marsai:writing-plans skill	Detailed task breakdown

The Process

Copy this checklist to track progress:

Brainstorming Progress:
- [ ] Prep: Autonomous Recon (repo/docs/commits reviewed, initial model shared)
- [ ] Phase 1: Understanding (purpose, constraints, criteria gathered)
- [ ] Phase 2: Exploration (2-3 approaches proposed and evaluated)
- [ ] Phase 3: Design Presentation (design validated in sections)
- [ ] Phase 4: Design Documentation (design written to docs/plans/)
- [ ] Phase 5: Worktree Setup (if implementing)
- [ ] Phase 6: Planning Handoff (if implementing)

Prep: Autonomous Recon

MANDATORY evidence (paste ALL): ls -la, git log --oneline -10, head -50 README.md, find . -name "*test*" | wc -l, check package.json/requirements.txt/go.mod.

Only after ALL evidence pasted: Form your model and share findings. Skip any = not following skill.

Question Budget

Maximum 3 questions per phase. More = insufficient research.

Question count:

• Phase 1: ___/3
• Phase 2: ___/3
• Phase 3: ___/3

Hit limit? Do research instead of asking.

Phase 1: Understanding

• Share your synthesized understanding first, then invite corrections or additions.
• Ask one focused question at a time, only for gaps you cannot close yourself.
• Use AskUserQuestion tool only when you need the human to make a decision among real alternatives.
• Gather: Purpose, constraints, success criteria (confirmed or amended by your partner)

Example summary + targeted question:

Based on the README and yesterday's commit, we're expanding localization to dashboard and billing emails; admin console is still untouched. Only gap I see is whether support responses need localization in this iteration. Did I miss anything important?

Phase Lock Rules

CRITICAL: Once you enter a phase, you CANNOT skip ahead.

• Asked a question? → WAIT for answer before solutions
• Proposed approaches? → WAIT for selection before design
• Started design? → COMPLETE before documentation

Violations:

• "While you consider that, here's my design..." → WRONG
• "I'll proceed with option 1 unless..." → WRONG
• "Moving forward with the assumption..." → WRONG

WAIT means WAIT. No assumptions.

Phase 2: Exploration

• Propose 2-3 different approaches
• For each: Core architecture, trade-offs, complexity assessment, and your recommendation
• Use AskUserQuestion tool to present approaches when you truly need a judgement call
• Lead with the option you prefer and explain why; invite disagreement if your partner sees it differently
• Own prioritization: if the repo makes priorities clear, state them and proceed rather than asking

Example using AskUserQuestion:

Question: "Which architectural approach should we use?"
Options:
  - "Direct API calls with retry logic" (simple, synchronous, easier to debug) ← recommended for current scope
  - "Event-driven with message queue" (scalable, complex setup, eventual consistency)
  - "Hybrid with background jobs" (balanced, moderate complexity, best of both)

I recommend the direct API approach because it matches existing patterns and minimizes new infrastructure. Let me know if you see a blocker that pushes us toward the other options.

Phase 3: Design Presentation

• Present in coherent sections; use ~200-300 words when introducing new material, shorter summaries once alignment is obvious
• Cover: Architecture, components, data flow, error handling, testing
• Check in at natural breakpoints rather than after every paragraph: "Stop me if this diverges from what you expect."
• Use open-ended questions to allow freeform feedback
• Assume ownership and proceed unless your partner redirects you

Design Acceptance Gate:

Design is NOT approved until human EXPLICITLY says one of:

• "Approved" / "Looks good" / "Proceed"
• "Let's implement that" / "Ship it"
• "Yes" (in response to "Shall I proceed?")

These do NOT mean approval:

• Silence / No response
• "Interesting" / "I see" / "Hmm"
• Questions about the design
• "What about X?" (that's requesting changes)

No explicit approval = keep refining

Phase 4: Design Documentation

After validating the design, write it to a permanent document:

• File location: docs/plans/YYYY-MM-DD-<topic>-design.md (use actual date and descriptive topic)
• RECOMMENDED SUB-SKILL: Use elements-of-style:writing-clearly-and-concisely (if available) for documentation quality
• Content: Capture the design as discussed and validated in Phase 3, organized into sections that emerged from the conversation
• Commit the design document to git before proceeding

Phase 5: Worktree Setup (for implementation)

When design is approved and implementation will follow:

• Announce: "I'm using the marsai:using-git-worktrees skill to set up an isolated workspace."
• REQUIRED SUB-SKILL: Use marsai:using-git-worktrees
• Follow that skill's process for directory selection, safety verification, and setup
• Return here when worktree ready

Phase 6: Planning Handoff

Ask: "Ready to create the implementation plan?"

When your human partner confirms (any affirmative response):

• Announce: "I'm using the marsai:writing-plans skill to create the implementation plan."
• REQUIRED SUB-SKILL: Use marsai:writing-plans
• Create detailed plan in the worktree

Question Patterns

When to Use AskUserQuestion Tool

Use AskUserQuestion when:

• You need your partner to make a judgement call among real alternatives
• You have a recommendation and can explain why it’s your preference
• Prioritization is ambiguous and cannot be inferred from existing materials

Best practices:

• State your preferred option and rationale inside the question so your partner can agree or redirect
• If you know the answer from repo/docs, state it as fact and proceed—no question needed
• When priorities are spelled out, acknowledge them and proceed rather than delegating the choice back to your partner

When to Use Open-Ended Questions

Use open-ended questions for:

• Phase 3: Design validation ("Does this look right so far?")
• When you need detailed feedback or explanation
• When partner should describe their own requirements
• When structured options would limit creative input

Frame them to confirm or expand your current understanding rather than reopening settled topics.

Example decision flow:

• "What authentication method?" → Use AskUserQuestion (2-4 options)
• "Does this design handle your use case?" → Open-ended (validation)

When to Revisit Earlier Phases

Trigger	Action
New constraint revealed	→ Return to Phase 1
Partner questions approach	→ Return to Phase 2
Requirements unclear	→ Return to Phase 1
Something doesn't make sense	→ Go back and clarify

Avoid forcing forward linearly when going backward would give better results.

Required Patterns

This skill uses these universal patterns:

• State Tracking: See skills/shared-patterns/state-tracking.md
• Failure Recovery: See skills/shared-patterns/failure-recovery.md
• Exit Criteria: See skills/shared-patterns/exit-criteria.md
• TodoWrite: See skills/shared-patterns/todowrite-integration.md

Apply ALL patterns when using this skill.

Key Principles

Principle	Application
One question at a time	Phase 1: Single targeted question only for gaps you can’t close yourself
Structured choices	Use AskUserQuestion tool for 2-4 options with trade-offs
YAGNI ruthlessly	Remove unnecessary features from all designs
Explore alternatives	Always propose 2-3 approaches before settling
Incremental validation	Present design in sections, validate each
Flexible progression	Go backward when needed - flexibility > rigidity
Own the initiative	Recommend priorities and next steps; ask if you should proceed only when requirements conflict
Announce usage	State skill usage at start of session

Blocker Criteria

STOP and report if:

Decision Type	Blocker Condition	Required Action
Phase progression	User has not explicitly approved design	STOP and wait for explicit approval
Question budget	Exceeded 3 questions per phase	STOP asking questions, do research instead
Phase lock	Attempting to skip ahead before phase completion	STOP and complete current phase first
Design validation	Received ambiguous response (not explicit approval)	STOP and clarify approval status
Sub-skill handoff	Required sub-skill unavailable or blocked	STOP and report blocker

Cannot Be Overridden

The following requirements CANNOT be waived:

• MUST follow phase lock rules - CANNOT skip ahead while waiting for answers
• MUST have explicit design approval - silence or "interesting" does not mean approval
• CANNOT exceed question budget of 3 per phase - research instead
• MUST paste autonomous recon evidence before forming model
• CANNOT skip sub-skill usage (marsai:writing-plans, marsai:using-git-worktrees) when applicable

Severity Calibration

Severity	Condition	Required Action
CRITICAL	Proceeding without explicit design approval	MUST stop immediately and obtain approval
CRITICAL	Skipping phases or phase lock violation	MUST return to correct phase
HIGH	Exceeding question budget without research	MUST do research before asking more questions
HIGH	Missing autonomous recon evidence	MUST gather and paste evidence
MEDIUM	Not using AskUserQuestion for structured choices	Should use proper tool for decisions
LOW	Minor documentation gaps in design doc	Fix in next iteration

Pressure Resistance

User Says	Your Response
"Just skip the exploration phase, I know what I want"	"MUST complete Phase 2 exploration to ensure we consider alternatives. This prevents costly rework later."
"I said it looks good, just proceed"	"MUST have explicit approval like 'approved' or 'proceed'. 'Looks good' is ambiguous - shall I proceed with implementation?"
"Stop asking questions and just build it"	"MUST gather understanding before building. I'll research the codebase to minimize questions while ensuring we build the right thing."
"We don't have time for all these phases"	"Phases exist to prevent expensive mistakes. Skipping them creates technical debt. MUST follow the process."

Anti-Rationalization Table

Rationalization	Why It's WRONG	Required Action
"User seems to approve, no need for explicit confirmation"	Implicit approval leads to misaligned implementations and wasted effort	MUST obtain explicit approval words
"I already know the codebase, skip autonomous recon"	Assumptions cause errors; evidence ensures accuracy	MUST paste recon evidence before proceeding
"This is a simple feature, phases are overkill"	Complexity is often hidden; phases reveal it	MUST complete all applicable phases
"User is impatient, I'll ask questions later"	Phase lock exists to prevent building wrong things	MUST wait for answers before solutions
"I can infer the decision from context"	Inference is not explicit choice; user must decide	MUST use AskUserQuestion for real decisions