---
description: Interactive brainstorming with serial CLI collaboration, idea expansion, and documented thought evolution. Sequential multi-perspective analysis for Codex.
argument-hint: "TOPIC=\"<idea or topic>\" [--perspectives=creative,pragmatic,systematic] [--max-ideas=<n>] [--focus=<area>] [--mode=creative|structured|balanced]"
---

# Codex Brainstorm-With-File Workflow

## Quick Start

Interactive brainstorming workflow with **documented thought evolution**. Expands initial ideas through questioning, multi-perspective analysis, and iterative refinement.

**Core workflow**: Seed Idea → Expand → Serial CLI Explore → Synthesize → Refine → Crystallize

**Key features**:
- **brainstorm.md**: Complete thought evolution timeline
- **Serial multi-perspective**: Creative → Pragmatic → Systematic (sequential)
- **Idea expansion**: Progressive questioning and exploration
- **Diverge-Converge cycles**: Generate options then focus on best paths

## Overview

This workflow enables iterative exploration and refinement of ideas through sequential phases:

1. **Seed Understanding** - Parse the initial idea and identify exploration vectors
2. **Divergent Exploration** - Gather codebase context and execute serial multi-perspective analysis
3. **Interactive Refinement** - Multi-round idea selection, deep-dive, and refinement
4. **Convergence & Crystallization** - Synthesize final ideas and generate recommendations

The key innovation is **documented thought evolution** that captures how ideas develop, perspectives differ, and insights emerge across all phases.

## Output Structure

```
.workflow/.brainstorm/BS-{slug}-{date}/
├── brainstorm.md                  # ⭐ Complete thought evolution timeline
├── exploration-codebase.json      # Phase 2: Codebase context
├── perspectives.json              # Phase 2: Serial CLI findings
├── synthesis.json                 # Phase 4: Final synthesis
└── ideas/                         # Phase 3: Individual idea deep-dives
    ├── idea-1.md
    ├── idea-2.md
    └── merged-idea-1.md
```

## Output Artifacts

### Phase 1: Seed Understanding

| Artifact | Purpose |
|----------|---------|
| `brainstorm.md` | Initialized with session metadata, seed expansion, and exploration vectors |
| Session variables | Topic slug, brainstorm mode, dimensions, exploration vectors |

### Phase 2: Divergent Exploration

| Artifact | Purpose |
|----------|---------|
| `exploration-codebase.json` | Codebase context: relevant files, patterns, architecture constraints |
| `perspectives.json` | Serial CLI findings: creative, pragmatic, systematic perspectives |
| Updated `brainstorm.md` | Round 2: Exploration results and multi-perspective analysis |

### Phase 3: Interactive Refinement

| Artifact | Purpose |
|----------|---------|
| `ideas/{idea-slug}.md` | Deep-dive analysis for selected ideas |
| Updated `brainstorm.md` | Round 3-6: User feedback, idea selections, refinement cycles |

### Phase 4: Convergence & Crystallization

| Artifact | Purpose |
|----------|---------|
| `synthesis.json` | Final synthesis: top ideas, recommendations, insights |
| Final `brainstorm.md` | Complete thought evolution with conclusions |

---

## Implementation Details

### Session Initialization

The workflow automatically generates a unique session identifier and directory structure based on the topic and current date (UTC+8).

**Session ID Format**: `BS-{slug}-{date}`
- `slug`: Lowercase alphanumeric + Chinese characters, max 40 chars
- `date`: YYYY-MM-DD format (UTC+8)

**Session Directory**: `.workflow/.brainstorm/{sessionId}/`

**Auto-Detection**: If session folder exists with brainstorm.md, automatically enters continue mode. Otherwise, creates new session.

**Brainstorm Modes**:
- `creative`: Emphasize novelty and innovation, relaxed constraints
- `structured`: Balance creativity with feasibility, realistic scope
- `balanced`: Default, moderate innovation with practical considerations

---

## Phase 1: Seed Understanding

**Objective**: Parse the initial idea, identify exploration vectors, scope preferences, and initialize the brainstorm document.

### Step 1.1: Parse Seed & Identify Dimensions

The workflow analyzes the topic text against predefined brainstorm dimensions.

**Brainstorm Dimensions**:

| Dimension | Keywords |
|-----------|----------|
| technical | 技术, technical, implementation, code, 实现, architecture |
| ux | 用户, user, experience, UX, UI, 体验, interaction |
| business | 业务, business, value, ROI, 价值, market |
| innovation | 创新, innovation, novel, creative, 新颖 |
| feasibility | 可行, feasible, practical, realistic, 实际 |
| scalability | 扩展, scale, growth, performance, 性能 |
| security | 安全, security, risk, protection, 风险 |

**Matching Logic**: Compare topic text against keyword lists to identify relevant dimensions.

### Step 1.2: Initial Scoping (New Session Only)

For new brainstorm sessions, gather user preferences before exploration.

**Brainstorm Mode** (Single-select):
- 创意模式 (Creative mode - 15-20 minutes)
- 平衡模式 (Balanced mode - 30-60 minutes)
- 深度模式 (Deep mode - 1-2+ hours)

**Focus Areas** (Multi-select):
- 技术方案 (Technical solutions)
- 用户体验 (User experience)
- 创新突破 (Innovation breakthroughs)
- 可行性评估 (Feasibility assessment)

### Step 1.3: Expand Seed into Exploration Vectors

Generate key questions that guide the brainstorming exploration.

**Exploration Vectors**:
1. **Core question**: What is the fundamental problem/opportunity?
2. **User perspective**: Who benefits and how?
3. **Technical angle**: What enables this technically?
4. **Alternative approaches**: What other ways could this be solved?
5. **Challenges**: What could go wrong or block success?
6. **Innovation angle**: What would make this 10x better?
7. **Integration**: How does this fit with existing systems/processes?

**Purpose**: These vectors guide each perspective's analysis and ensure comprehensive exploration.

### Step 1.4: Initialize brainstorm.md

Create the main brainstorm document with session metadata and expansion content.

**brainstorm.md Structure**:
- **Header**: Session ID, topic, start time, brainstorm mode, dimensions
- **Initial Context**: Focus areas, depth level, constraints
- **Seed Expansion**: Original idea + exploration vectors
- **Thought Evolution Timeline**: Round-by-round findings
- **Current Ideas**: To be populated after exploration

**Success Criteria**:
- Session folder created successfully
- brainstorm.md initialized with all metadata
- Brainstorm mode and dimensions identified
- Exploration vectors generated
- User preferences captured

---

## Phase 2: Divergent Exploration

**Objective**: Gather codebase context and execute serial (sequential) multi-perspective analysis to generate diverse viewpoints.

**Execution Model**: Serial execution (creative → pragmatic → systematic) - each perspective completes before starting the next, allowing later perspectives to build on earlier findings.

### Step 2.1: Codebase Context Gathering

Use built-in tools to understand the codebase structure and identify relevant code.

**Context Gathering Activities**:
1. **Get project structure** - Execute `ccw tool exec get_modules_by_depth '{}'` to understand module organization
2. **Search for related code** - Use Grep/Glob to find files matching topic keywords
3. **Read project tech context** - Load `.workflow/project-tech.json` if available
4. **Analyze patterns** - Identify common code patterns and architecture decisions

**exploration-codebase.json Structure**:
- `relevant_files[]`: Files related to the topic with relevance indicators
- `existing_patterns[]`: Common code patterns and architectural styles
- `architecture_constraints[]`: Project-level constraints
- `integration_points[]`: Key integration patterns between modules
- `_metadata`: Timestamp and context information

### Step 2.2: Serial Multi-Perspective Analysis

Execute perspectives sequentially: Creative (Gemini) → Pragmatic (Codex) → Systematic (Claude).

**Execution Guideline**: Each perspective builds on codebase context and runs to completion before the next begins.

**Perspective Definitions**:

| Perspective | Purpose | Focus |
|-------------|---------|-------|
| Creative | Innovation and novelty | Cross-domain inspiration, challenging assumptions, moonshot ideas |
| Pragmatic | Implementation reality | Technical feasibility, effort estimates, quick wins, blockers |
| Systematic | Architecture thinking | Problem decomposition, patterns, dependencies, scalability |

**Analysis Approach**:
- Each perspective receives the exploration context
- Creative generates novel ideas first
- Pragmatic evaluates creative ideas for feasibility
- Systematic provides architectural structure and tradeoffs
- Each builds understanding progressively

### Step 2.3: Aggregate Multi-Perspective Findings

Consolidate results from all three perspectives into a unified findings document.

**perspectives.json Structure**:
- `session_id`: Reference to brainstorm session
- `timestamp`: Completion time
- `topic`: Original idea/topic
- `creative[]`: Creative perspective findings (ideas with novelty ratings)
- `pragmatic[]`: Pragmatic perspective findings (approaches with effort ratings)
- `systematic[]`: Systematic perspective findings (architectural options)
- `synthesis`: Convergent themes, conflicting views, unique contributions
- `key_findings[]`: Main insights across all perspectives

**Aggregation Activities**:
1. Extract key findings from each perspective's CLI analysis
2. Identify themes all perspectives agree on
3. Note conflicting views and tradeoffs
4. Extract unique contributions from each perspective
5. Organize findings by brainstorm dimension

### Step 2.4: Update brainstorm.md

Append exploration results to the brainstorm timeline.

**Round 2 Sections** (Multi-Perspective Exploration):
- **Creative Perspective**: Novel ideas with novelty/impact ratings
- **Pragmatic Perspective**: Practical approaches with effort/risk ratings
- **Systematic Perspective**: Architectural options with tradeoff analysis
- **Perspective Synthesis**: Convergent themes, conflicts, unique contributions

**Documentation Standards**:
- Include evidence from codebase exploration
- Organize findings by perspective
- Highlight areas of agreement and disagreement
- Note key assumptions and reasoning

**Success Criteria**:
- `exploration-codebase.json` created with comprehensive context
- `perspectives.json` created with all three perspective analyses
- `brainstorm.md` updated with Round 2 results
- All CLI executions completed successfully
- Ready for interactive refinement phase

---

## Phase 3: Interactive Refinement

**Objective**: Iteratively refine ideas through multi-round user-guided exploration cycles with deep dives, challenge testing, and idea merging.

**Max Rounds**: 6 refinement rounds (can exit earlier if user indicates completion)

### Step 3.1: Present Findings & Gather User Direction

Display current ideas and perspectives to the user.

**Presentation Content**:
- Top ideas from each perspective with ratings
- Convergent themes and areas of agreement
- Conflicting views and tradeoffs
- Open questions for further exploration

**User Feedback Options** (Single-select):

| Option | Purpose | Next Action |
|--------|---------|------------|
| **深入探索** | Explore selected ideas in detail | Execute deep-dive CLI analysis |
| **继续发散** | Generate more ideas | Additional idea generation from new angles |
| **挑战验证** | Test ideas critically | Devil's advocate challenge |
| **合并综合** | Combine multiple ideas | Synthesize selected ideas into unified concept |
| **准备收敛** | Begin convergence | Exit refinement loop for synthesis |

### Step 3.2: Deep Dive on Selected Ideas

When user selects "deep dive", provide comprehensive analysis of ideas.

**Deep Dive Strategy**:
- Elaborate core concept with specifics
- Identify implementation requirements and dependencies
- Analyze potential challenges and propose mitigations
- Suggest proof-of-concept approach
- Define success metrics and acceptance criteria

**Analysis Scope**:
- Detailed concept breakdown
- Technical requirements and dependencies
- Risk/challenge analysis with proposed solutions
- MVP definition for proof-of-concept
- Success criteria and measurement approach

### Step 3.3: Devil's Advocate Challenge

When user selects "challenge", critically test ideas.

**Challenge Strategy**:
- Identify strongest objections to each idea
- Challenge core assumptions and reasoning
- Identify failure scenarios and edge cases
- Consider competitive or alternative solutions
- Assess whether the idea solves the right problem

**Analysis Scope**:
- 3+ strongest objections per idea
- Challenge to assumptions and reasoning
- Failure scenarios and recovery approaches
- Alternative solutions that could compete
- Survivability rating after challenge (1-5)

### Step 3.4: Merge Multiple Ideas

When user selects "merge", synthesize complementary ideas.

**Merge Strategy**:
- Identify complementary elements and strengths
- Resolve contradictions and conflicts
- Create unified concept preserving key strengths
- Ensure coherence and viability of merged result

**Analysis Scope**:
- Complementary elements from each source idea
- Contradiction resolution or documented tradeoffs
- New combined strengths and capabilities
- Implementation considerations for merged approach

### Step 3.5: Document Each Round

Update brainstorm.md with results from each refinement round.

**Round N Sections** (Rounds 3-6):

| Section | Content |
|---------|---------|
| User Direction | Action taken and ideas selected |
| Findings | New findings and clarifications |
| Idea Updates | Changes to idea scores and status |
| Insights | Key learnings and realizations |
| Next Directions | Suggested follow-up investigations |

**Documentation Standards**:
- Clear timestamps and action taken
- Evidence-based findings with code references
- Updated idea rankings and status changes
- Explicit tracking of assumption changes
- Organized by exploration vector

**Success Criteria**:
- User feedback processed for each round
- `brainstorm.md` updated with all refinement rounds
- Ideas in `ideas/` folder for selected deep-dives
- Exit condition reached (user selects converge or max rounds)

---

## Phase 4: Convergence & Crystallization

**Objective**: Synthesize final ideas, generate conclusions and recommendations, and offer next steps.

### Step 4.1: Consolidate Insights

Extract and synthesize all findings from refinement rounds into final conclusions.

**Consolidation Activities**:
1. Review all refinement rounds and accumulated findings
2. Rank ideas by score, feasibility, and impact
3. Identify top 5 viable ideas
4. Extract key learnings and insights
5. Generate recommendations with rationale

**synthesis.json Structure**:
- `session_id`: Session identifier
- `topic`: Original idea/topic
- `completed`: Completion timestamp
- `total_rounds`: Number of refinement rounds
- `top_ideas[]`: Top 5 ranked ideas with scores and next steps
- `parked_ideas[]`: Ideas parked for future consideration
- `key_insights[]`: Key learnings from brainstorming process
- `recommendations`: Primary recommendation and alternatives
- `follow_up[]`: Suggested next steps (implementation, research, validation)

**Idea Format**:
- `title`: Clear, descriptive title
- `description`: Complete concept description
- `source_perspective`: Which perspective(s) contributed
- `score`: Final viability score (1-10)
- `novelty`: Novelty/innovation rating (1-5)
- `feasibility`: Implementation feasibility (1-5)
- `key_strengths`: Main advantages and benefits
- `main_challenges`: Key challenges and limitations
- `next_steps`: Recommended actions to pursue

### Step 4.2: Final brainstorm.md Update

Append conclusions section and finalize the thinking document.

**Synthesis & Conclusions Section**:
- **Executive Summary**: High-level overview of brainstorming results
- **Top Ideas**: Ranked list with descriptions and strengths/challenges
- **Primary Recommendation**: Best path forward with clear rationale
- **Alternative Approaches**: Other viable options with tradeoff analysis
- **Parked Ideas**: Future considerations with potential triggers
- **Key Insights**: Important learnings from the process

**Session Statistics**:
- Total refinement rounds completed
- Ideas generated and evaluated
- Ideas survived challenges
- Perspectives used (creative, pragmatic, systematic)
- Artifacts generated

### Step 4.3: Post-Completion Options

Offer user follow-up actions based on brainstorming results.

**Available Options**:

| Option | Purpose | Action |
|--------|---------|--------|
| **创建实施计划** | Plan implementation of top idea | Launch `workflow:lite-plan` |
| **创建Issue** | Track top ideas for later | Launch `issue:new` with ideas |
| **深入分析** | Analyze top idea in detail | Launch `workflow:analyze-with-file` |
| **导出分享** | Generate shareable report | Create formatted report document |
| **完成** | No further action | End workflow |

**Success Criteria**:
- `synthesis.json` created with complete synthesis
- `brainstorm.md` finalized with all conclusions
- User offered meaningful next step options
- Session complete and all artifacts available

---

## Configuration

### Brainstorm Dimensions Reference

Dimensions guide brainstorming scope and focus:

| Dimension | Keywords | Best For |
|-----------|----------|----------|
| technical | 技术, technical, implementation, code | Implementation approaches |
| ux | 用户, user, experience, UI | User-facing design ideas |
| business | 业务, business, value | Business model innovations |
| innovation | 创新, innovation, novel | Breakthrough ideas |
| feasibility | 可行, feasible, practical | Realistic approaches |
| scalability | 扩展, scale, growth | Large-scale solutions |
| security | 安全, security, risk | Security considerations |

### Brainstorm Modes

| Mode | Duration | Intensity | Complexity |
|------|----------|-----------|-----------|
| Creative | 15-20 min | High novelty | Exploratory |
| Balanced | 30-60 min | Mixed | Moderate |
| Deep | 1-2+ hours | Comprehensive | Detailed |

---

## Error Handling & Recovery

| Situation | Action | Recovery |
|-----------|--------|----------|
| CLI timeout | Retry with shorter prompt | Skip perspective or reduce depth |
| No good ideas | Reframe problem or adjust constraints | Try new exploration angles |
| User disengaged | Summarize progress and offer break | Save state for later continuation |
| Perspectives conflict | Present as tradeoff options | Let user select preferred direction |
| Max rounds reached | Force synthesis phase | Highlight unresolved questions |
| Session folder conflict | Append timestamp suffix | Create unique folder |

---

## Iteration Patterns

### First Brainstorm Session

```
User initiates: TOPIC="idea or topic"
   ├─ No session exists → New session mode
   ├─ Parse topic and identify dimensions
   ├─ Scope with user (focus, depth, mode)
   ├─ Create brainstorm.md
   ├─ Expand seed into vectors
   ├─ Gather codebase context
   ├─ Execute serial CLI perspectives (Creative → Pragmatic → Systematic)
   ├─ Aggregate findings
   └─ Enter multi-round refinement loop
```

### Continue Existing Session

```
User resumes: TOPIC="same topic"
   ├─ Session exists → Continue mode
   ├─ Load previous brainstorm.md
   ├─ Load perspectives.json
   └─ Resume from last refinement round
```

### Refinement Loop (Rounds 3-6)

```
Each round:
   ├─ Present current findings and top ideas
   ├─ Gather user feedback (deep dive/diverge/challenge/merge/converge)
   ├─ Process response:
   │   ├─ Deep Dive → CLI analysis elaborating on selected ideas
   │   ├─ Diverge → CLI analysis generating new ideas
   │   ├─ Challenge → CLI analysis with devil's advocate
   │   ├─ Merge → CLI analysis synthesizing multiple ideas
   │   └─ Converge → Exit loop for synthesis
   ├─ Update brainstorm.md
   └─ Repeat until user selects converge or max rounds reached
```

### Completion Flow

```
Final synthesis:
   ├─ Consolidate all findings into top ideas
   ├─ Generate synthesis.json
   ├─ Update brainstorm.md with final conclusions
   ├─ Offer follow-up options
   └─ Archive session artifacts
```

---

## Best Practices

### Before Starting Brainstorm

1. **Clear Topic Definition**: Detailed topics lead to better dimension identification
2. **User Context**: Understanding preferences helps guide brainstorming intensity
3. **Scope Understanding**: Being clear about time/scope expectations sets correct exploration level

### During Brainstorming

1. **Review Perspectives**: Check all three perspectives before refinement rounds
2. **Document Assumptions**: Track what you think is true for correction later
3. **Use Continue Mode**: Resume sessions to build on previous exploration
4. **Embrace Conflicts**: Perspective conflicts often reveal important tradeoffs
5. **Iterate Thoughtfully**: Each refinement round should meaningfully advance ideas

### Documentation Practices

1. **Evidence-Based**: Every idea should reference codebase patterns or feasibility analysis
2. **Perspective Diversity**: Capture viewpoints from all three perspectives
3. **Timeline Clarity**: Use clear timestamps for traceability
4. **Evolution Tracking**: Document how ideas changed and evolved
5. **Action Items**: Generate specific, implementable recommendations


---

**Now execute the brainstorm-with-file workflow for topic**: $TOPIC