Codex Brainstorm-With-File Prompt

Overview

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

Core workflow: Seed Idea → Expand → Multi-Perspective Explore → Research → Refine → Crystallize → Next Step

Key features:

• brainstorm.md: Complete thought evolution timeline
• Multi-perspective analysis: Creative + Pragmatic + Systematic (serial, inline)
• External research: Web search for inspiration, patterns, and best practices via web.run
• Idea expansion: Progressive questioning and exploration
• Diverge-Converge cycles: Generate options then focus on best paths
• Progress tracking: functions.update_plan for real-time phase progress visibility
• Structured handoff: Terminal gate with execution planning, issue creation, or completion

Auto Mode

When --yes or -y: Auto-confirm exploration decisions, use recommended perspectives, skip interactive scoping.

Quick Start

bash
# Basic usage
/codex:brainstorm-with-file TOPIC="How to improve developer onboarding experience"

# With perspective selection
/codex:brainstorm-with-file TOPIC="New caching strategy" --perspectives=creative,pragmatic,systematic

# Continue existing session
/codex:brainstorm-with-file TOPIC="caching strategy" --continue

# Auto mode (skip confirmations)
/codex:brainstorm-with-file -y TOPIC="Plugin architecture ideas"

Target Topic

$TOPIC

Configuration

| Flag | Default | Description | |------|---------|-------------| | -y, --yes | false | Auto-confirm all decisions | | --continue | false | Continue existing session | | --perspectives | creative,pragmatic,systematic | Comma-separated perspective list | | --max-ideas | 15 | Maximum ideas to track |

Session ID format: BS-{YYYY-MM-DD}-{slug}

• slug: lowercase, alphanumeric + CJK characters, max 40 chars
• date: YYYY-MM-DD (UTC+8)
• Auto-detect continue: session folder + brainstorm.md exists → continue mode

Brainstorm Flow

Step 0: Session Setup
   ├─ Parse topic, flags (--perspectives, --continue, -y)
   ├─ Generate session ID: BS-{date}-{slug}
   ├─ Create session folder (or detect existing → continue mode)
   └─ functions.update_plan (5 phases: Seed → Explore → Refine → Converge → GATE)

Step 1: Seed Understanding
   ├─ Parse topic, identify brainstorm dimensions
   ├─ Role/perspective selection with user (or auto)
   ├─ Initial scoping via functions.request_user_input (mode, focus, constraints)
   ├─ Expand seed into exploration vectors
   └─ Initialize brainstorm.md

Step 2: Divergent Exploration (Inline, No Agents)
   ├─ Detect codebase → search relevant modules, patterns
   │   ├─ Run `ccw spec load --category exploration` (if spec system available)
   │   └─ Use Grep, Glob, Read, mcp__ace-tool__search_context
   ├─ Multi-perspective analysis (serial, inline)
   │   ├─ Creative perspective: innovation, cross-domain, challenge assumptions
   │   ├─ Pragmatic perspective: feasibility, effort, blockers
   │   └─ Systematic perspective: decomposition, patterns, scalability
   ├─ External research via web.run (optional — patterns, best practices, inspiration)
   ├─ Aggregate findings → perspectives.json + research.json
   ├─ Update brainstorm.md with Round 1
   └─ Initial Idea Coverage Check

Step 3: Interactive Refinement (Multi-Round, max 6)
   ├─ Present current ideas and perspectives (Cumulative Context)
   ├─ Record findings to brainstorm.md BEFORE updating Current Ideas
   ├─ Gather user feedback via functions.request_user_input
   ├─ Process response:
   │   ├─ Deep Dive → deeper inline analysis on selected ideas
   │   ├─ Diverge → new inline analysis with different angles
   │   ├─ Challenge → devil's advocate inline analysis
   │   ├─ Merge → synthesize complementary ideas inline
   │   ├─ 外部研究 → web.run for external inspiration/validation
   │   └─ Converge → exit loop for synthesis
   ├─ Update brainstorm.md with round details
   └─ Repeat until user selects converge or max rounds

Step 4: Convergence & Crystallization
   ├─ Consolidate all insights → synthesis.json
   ├─ Update brainstorm.md with final synthesis
   ├─ Batch top-idea review via functions.request_user_input
   └─ MANDATORY Terminal Gate: 执行任务 / 产出Issue / 完成
       ├─ Execute Task → handoff-spec.json with implementation scope
       ├─ Create Issue → display issue creation command
       └─ Done → end workflow

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 | Individual perspective outputs (creative, pragmatic, systematic) | | perspectives.json | Aggregated findings with synthesis (convergent/conflicting themes) | | Updated brainstorm.md | Round 1: Exploration results and multi-perspective analysis |

Phase 3: Interactive Refinement

| Artifact | Purpose | |----------|---------| | ideas/{idea-slug}.md | Deep-dive analysis for selected ideas | | ideas/merged-idea-{n}.md | Merged idea documents | | Updated brainstorm.md | Round 2-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 |

Recording Protocol

CRITICAL: During brainstorming, the following situations MUST trigger immediate recording to brainstorm.md:

| Trigger | What to Record | Target Section | |---------|---------------|----------------| | Idea generated | Idea content, source perspective, novelty/feasibility ratings | #### Ideas Generated | | Perspective shift | Old framing → new framing, trigger reason | #### Decision Log | | User feedback | User's original input, which ideas selected/rejected | #### User Input | | Assumption challenged | Original assumption → challenge result, survivability | #### Challenged Assumptions | | Ideas merged | Source ideas, merged concept, what was preserved/discarded | #### Decision Log | | Scope adjustment | Before/after scope, trigger reason | #### Decision Log |

Decision Record Format

markdown
> **Decision**: [Description of the decision]
> - **Context**: [What triggered this decision]
> - **Options considered**: [Alternatives evaluated]
> - **Chosen**: [Selected approach] — **Reason**: [Rationale]
> - **Rejected**: [Why other options were discarded]
> - **Impact**: [Effect on brainstorming direction]

Narrative Synthesis Format

Append after each round update:

markdown
### Round N: Narrative Synthesis
**Starting point**: Based on previous round's [conclusions/questions], this round explored [starting point].
**Key progress**: [New ideas/findings] [confirmed/refuted/expanded] previous understanding of [topic area].
**Decision impact**: User selected [feedback type], directing brainstorming toward [adjusted/deepened/maintained].
**Current state**: After this round, top ideas are [updated idea rankings].
**Open directions**: [remaining exploration angles for next round]

Implementation Details

Phase 0: Session Initialization

javascript
const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()

// Parse flags
const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
const continueMode = $ARGUMENTS.includes('--continue')
const perspectivesMatch = $ARGUMENTS.match(/--perspectives[=\s]([\w,]+)/)
const selectedPerspectiveNames = perspectivesMatch
  ? perspectivesMatch[1].split(',')
  : ['creative', 'pragmatic', 'systematic']

// Extract topic
const topic = $ARGUMENTS.replace(/--yes|-y|--continue|--perspectives[=\s][\w,]+|--max-ideas[=\s]\d+|TOPIC=/g, '').replace(/^["']|["']$/g, '').trim()

// Determine project root
const projectRoot = functions.exec_command('git rev-parse --show-toplevel 2>/dev/null || pwd').trim()

const slug = topic.toLowerCase().replace(/[^a-z0-9\u4e00-\u9fa5]+/g, '-').substring(0, 40)
const dateStr = getUtc8ISOString().substring(0, 10)
const sessionId = `BS-${dateStr}-${slug}`
const sessionFolder = `${projectRoot}/.workflow/.brainstorm/${sessionId}`

// Auto-detect continue: session folder + brainstorm.md exists → continue mode
// If continue → load brainstorm.md + perspectives, resume from last round
functions.exec_command(`mkdir -p ${sessionFolder}`)

// Initialize progress tracking (MANDATORY)
functions.update_plan([
  { id: "phase-1", title: "Phase 1: Seed Understanding", status: "in_progress" },
  { id: "phase-2", title: "Phase 2: Divergent Exploration", status: "pending" },
  { id: "phase-3", title: "Phase 3: Interactive Refinement", status: "pending" },
  { id: "phase-4", title: "Phase 4: Convergence & Crystallization", status: "pending" },
  { id: "next-step", title: "GATE: Post-Completion Next Step", status: "pending" }
])

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

Match topic keywords against brainstorm dimensions (see Dimensions Reference):

javascript
// Match topic text against keyword lists from Dimensions Reference
// If multiple dimensions match, include all
// If none match, default to "technical" and "innovation"
const dimensions = identifyDimensions(topic, BRAINSTORM_DIMENSIONS)

##### Step 1.2: Role Selection

Recommend roles based on topic keywords, then let user confirm or override.

Professional Roles (recommended based on topic keywords):

| Role | Perspective Focus | Keywords | |------|------------------|----------| | system-architect | Architecture, patterns | 架构, architecture, system, 系统, design pattern | | product-manager | Business value, roadmap | 产品, product, feature, 功能, roadmap | | ui-designer | Visual design, interaction | UI, 界面, interface, visual, 视觉 | | ux-expert | User research, usability | UX, 体验, experience, user, 用户 | | data-architect | Data modeling, storage | 数据, data, database, 存储, storage | | test-strategist | Quality, testing | 测试, test, quality, 质量, QA | | subject-matter-expert | Domain knowledge | 领域, domain, industry, 行业, expert |

Simple Perspectives (fallback — always available):

| Perspective | Focus | Best For | |-------------|-------|----------| | creative | Innovation, cross-domain | Generating novel ideas | | pragmatic | Implementation, feasibility | Reality-checking ideas | | systematic | Architecture, structure | Organizing solutions |

Selection Strategy:

1. Auto mode: Select top 3 recommended professional roles based on keyword matching
2. Manual mode: Present recommended roles + "Use simple perspectives" option
3. Continue mode: Use roles from previous session

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

For new brainstorm sessions, gather user preferences before exploration (skipped in auto mode or continue mode):

javascript
if (!autoYes && !continueMode) {
  // Single batch: Mode + Focus + Constraints (max 4 questions per call)
  const scoping = functions.request_user_input({
    questions: [
      {
        header: "Mode",       // max 12 chars
        question: "Select brainstorming intensity:",
        multiSelect: false,
        options: [
          { label: "Balanced (Recommended)", description: "Moderate, 3 perspectives" },
          { label: "Creative", description: "Fast, high novelty, 1 perspective" },
          { label: "Deep", description: "Comprehensive, 3 perspectives + deep refinement" }
        ]
      },
      {
        header: "Focus",
        question: "Select brainstorming focus areas:",
        multiSelect: true,
        options: generateFocusOptions(dimensions) // Dynamic based on dimensions
      },
      {
        header: "Constraints",
        question: "Any constraints to consider?",
        multiSelect: true,
        options: [
          { label: "Existing Arch", description: "Must fit current system" },
          { label: "Time Limited", description: "Short implementation timeline" },
          { label: "Resource Limited", description: "Limited team/budget" },
          { label: "No Constraints", description: "Blue-sky thinking" }
        ]
      }
    ]
  })
}

##### Step 1.4: Expand Seed into Exploration Vectors

Generate key questions that guide the brainstorming exploration. Done inline — no agent delegation.

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?

Analyze the topic inline against user focus areas and constraints to produce 5-7 exploration vectors.

##### Step 1.5: Initialize brainstorm.md

javascript
const brainstormMd = `# Brainstorm Session

**Session ID**: ${sessionId}
**Topic**: ${topic}
**Started**: ${getUtc8ISOString()}
**Dimensions**: ${dimensions.join(', ')}
**Mode**: ${brainstormMode}

## Table of Contents
<!-- TOC: Auto-updated after each round/phase. -->
- [Session Context](#session-context)
- [Current Ideas](#current-ideas)
- [Thought Evolution Timeline](#thought-evolution-timeline)

## Current Ideas
<!-- REPLACEABLE BLOCK: Overwrite (not append) after each round with latest ranked ideas. -->

> To be populated after exploration.

## Session Context
- Focus areas: ${focusAreas.join(', ')}
- Perspectives: ${selectedPerspectiveNames.join(', ')}
- Constraints: ${constraints.join(', ')}
- Mode: ${brainstormMode}

## Exploration Vectors
${explorationVectors.map((v, i) => `${i+1}. ${v}`).join('\n')}

## Initial Decisions
> Record why these perspectives and focus areas were selected.

---

## Thought Evolution Timeline

> Rounds will be appended below as brainstorming progresses.

---

## Decision Trail

> Consolidated critical decisions across all rounds (populated in Phase 4).
`
Write(`${sessionFolder}/brainstorm.md`, brainstormMd)

Success Criteria:

• Session folder created with brainstorm.md initialized
• Brainstorm dimensions identified and user preferences captured
• Initial decisions recorded: Perspective selection rationale, excluded options with reasons
• Exploration vectors generated
• 1-3 perspectives selected

Phase 2: Divergent Exploration

Objective: Gather codebase context and execute multi-perspective analysis to generate diverse viewpoints. All exploration done inline — no agent delegation.

##### Step 2.1: Detect Codebase & Explore

javascript
const hasCodebase = functions.exec_command(`
  test -f package.json && echo "nodejs" ||
  test -f go.mod && echo "golang" ||
  test -f Cargo.toml && echo "rust" ||
  test -f pyproject.toml && echo "python" ||
  test -f pom.xml && echo "java" ||
  test -d src && echo "generic" ||
  echo "none"
`).trim()

if (hasCodebase !== 'none') {
  // 1. Read project metadata (if exists)
  //    - Run `ccw spec load --category exploration` (load project specs)
  //    - Run `ccw spec load --category debug` (known issues and root-cause notes)
  //    - .workflow/specs/*.md (project conventions)

  // 2. Search codebase for relevant content
  //    Use: Grep, Glob, Read, or mcp__ace-tool__search_context
  //    Focus on: modules/components, patterns/structure, integration points, config/dependencies

  // 3. Write findings
  Write(`${sessionFolder}/exploration-codebase.json`, JSON.stringify({
    project_type: hasCodebase,
    relevant_files: [...],    // [{path, relevance, summary}]
    existing_patterns: [...], // [{pattern, files, description}]
    architecture_constraints: [...], // Constraints found
    integration_points: [...], // [{location, description}]
    key_findings: [...],      // Main insights from code search
    _metadata: { timestamp: getUtc8ISOString(), exploration_scope: '...' }
  }, null, 2))
}

##### Step 2.2: Multi-Perspective Analysis (Serial, Inline)

Analyze from each selected perspective. All analysis done inline by the AI — no agents.

Perspective Definitions:

| Perspective | Focus | Tasks | |-------------|-------|-------| | Creative | Innovation, cross-domain | Think beyond obvious, explore cross-domain inspiration, challenge assumptions, generate moonshot ideas | | Pragmatic | Implementation reality | Evaluate feasibility, identify existing patterns/libraries, estimate complexity, highlight blockers | | Systematic | Architecture thinking | Decompose problem, identify architectural patterns, map dependencies, consider scalability |

Serial execution — analyze each perspective sequentially:

javascript
const perspectives = ['creative', 'pragmatic', 'systematic']

perspectives.forEach(perspective => {
  // Analyze inline using exploration-codebase.json as context
  // Generate ideas from this perspective's focus
  Write(`${sessionFolder}/perspectives/${perspective}.json`, JSON.stringify({
    perspective: perspective,
    ideas: [        // 3-5 ideas per perspective
      { title: '...', description: '...', novelty: 1-5, feasibility: 1-5, rationale: '...' }
    ],
    key_findings: [...],
    challenged_assumptions: [...],
    open_questions: [...],
    _metadata: { perspective, timestamp: getUtc8ISOString() }
  }, null, 2))
})

##### Step 2.3: Aggregate Multi-Perspective Findings

javascript
// Update progress
functions.update_plan([{ id: "phase-2", title: "Phase 2: Divergent Exploration", status: "in_progress" }])

const synthesis = {
  session_id: sessionId,
  timestamp: getUtc8ISOString(),
  topic,

  // Individual perspective findings
  creative: readJson(`${sessionFolder}/perspectives/creative.json`),
  pragmatic: readJson(`${sessionFolder}/perspectives/pragmatic.json`),
  systematic: readJson(`${sessionFolder}/perspectives/systematic.json`),

  // Cross-perspective synthesis
  synthesis: {
    convergent_themes: [...],    // What all perspectives agree on
    conflicting_views: [...],    // Where perspectives differ
    unique_contributions: [...]  // Insights unique to specific perspectives
  },

  // Aggregated for refinement
  aggregated_ideas: [...],  // Merged and deduplicated ideas from all perspectives
  key_findings: [...]       // Main insights across all perspectives
}
Write(`${sessionFolder}/perspectives.json`, JSON.stringify(synthesis, null, 2))

##### Step 2.3b: External Research (Optional)

Search for external inspiration, industry best practices, and prior art to enrich brainstorming context.

javascript
// Triggered when: topic involves established patterns, industry trends, or competitive landscape
const researchQueries = generateResearchQueries(topic, dimensions)

researchQueries.forEach(query => {
  const results = web.run({ search_query: query })
  // Extract: patterns, inspiration, best practices, case studies
})

// Write research findings
Write(`${sessionFolder}/research.json`, JSON.stringify({
  queries: researchQueries,
  findings: [...],   // [{source, insight, relevance_to_topic}]
  inspiration: [...], // Cross-domain ideas from external sources
  best_practices: [...],
  _metadata: { timestamp: getUtc8ISOString() }
}, null, 2))

// Merge research findings into perspectives.json synthesis
// Update convergent_themes and unique_contributions with external evidence

##### Step 2.4: Update brainstorm.md

Append Round 1 with exploration results using the Round Documentation Pattern.

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

##### Step 2.5: Initial Idea Coverage Check

javascript
// Check exploration vectors against Round 1 findings
appendToBrainstorm(`
#### Initial Idea Coverage Check (Post-Exploration)
${explorationVectors.map((vector, i) => {
  const status = assessCoverage(vector, explorationFindings)
  return `- ${status.icon} Vector ${i+1}: ${vector} — ${status.detail}`
}).join('\n')}

> Next rounds will focus on uncovered and in-progress vectors.
`)

Success Criteria:

• exploration-codebase.json created with codebase context (if codebase exists)
• perspectives/.json created for each perspective
• perspectives.json created with aggregated findings and synthesis
• brainstorm.md updated with Round 1 results
• Initial Idea Coverage Check completed
• Key findings recorded with evidence and ratings

Phase 3: Interactive Refinement

Objective: Iteratively refine ideas through multi-round user-guided exploration cycles. Max Rounds: 6. All analysis done inline.

Auto mode behavior (--yes):

• Balanced/Deep mode: Run 2 auto-rounds (1× Deep Dive on top 2 ideas, 1× Challenge on top 3 ideas), then auto-converge
• Creative mode: Run 1 auto-round (1× Diverge), then auto-converge
• Skip user direction prompts; auto-select based on idea scores

Cumulative Context Rule: Each round's analysis MUST include ALL prior findings as context. Never analyze in isolation — always build on:

• Previous rounds' ideas and ratings
• User feedback from all prior rounds
• Research findings (if any)
• Challenged assumptions and their outcomes

Record-Before-Continue Rule: MUST write round findings to brainstorm.md BEFORE updating Current Ideas or presenting next interaction.

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

Current Understanding Summary (Round >= 2, BEFORE presenting new findings):

• Generate 1-2 sentence recap of top ideas and last round's direction
• Example: "Top ideas so far: idea1], idea2]. Last round deepened/challenged/merged]. Here are the latest findings:"

javascript
// Update progress
functions.update_plan([{ id: "phase-3", title: "Phase 3: Interactive Refinement", status: "in_progress" }])

if (!autoYes) {
  // Dynamic options based on round context
  const baseOptions = [
    { label: "Deep Dive", description: "Explore selected ideas in detail" },
    { label: "Diverge More", description: "Generate more ideas from different angles" },
    { label: "Challenge", description: "Devil's advocate — test ideas critically" },
    { label: "Merge Ideas", description: "Combine complementary ideas" }
  ]

  // Add research option if not yet done or if new angles emerged
  if (!researchDone || newAnglesEmerged) {
    baseOptions.push({ label: "外部研究", description: "Search for external inspiration and best practices" })
  }

  // Always include converge as final option
  baseOptions.push({ label: "Ready to Converge", description: "Sufficient ideas, proceed to synthesis" })

  const feedback = functions.request_user_input({
    questions: [{
      header: "Direction",   // max 12 chars
      question: `Brainstorm round ${round}: What would you like to do next?`,
      multiSelect: false,
      options: baseOptions.slice(0, 4) // max 4 options per schema
    }]
  })
}

##### Step 3.2: Process User Response

Recording Checkpoint: Regardless of option selected, MUST record to brainstorm.md:

• User's original choice and expression
• Impact on brainstorming direction
• If direction changed, record a full Decision Record

| Response | Action | |----------|--------| | Deep Dive | Ask which ideas to explore. Inline analysis: elaborate concept, identify requirements/dependencies, analyze challenges, suggest PoC approach, define success metrics. Write to ideas/{idea-slug}.md. | | Diverge More | Inline analysis with different angles: alternative framings, cross-domain inspiration, what-if scenarios, constraint relaxation. Generate new ideas. | | Challenge | Inline devil's advocate analysis: 3 strongest objections per idea, challenge assumptions, failure scenarios, competitive alternatives, survivability rating (1-5). | | Merge Ideas | Ask which ideas to merge. Inline synthesis: identify complementary elements, resolve contradictions, create unified concept, preserve strengths. Write to ideas/merged-idea-{n}.md. | | 外部研究 | Execute web.run with topic-specific queries. Search for: industry patterns, competitive solutions, best practices, academic research. Merge findings into current round. Update research.json. | | Ready to Converge | Record why concluding. Exit loop → Phase 4. |

##### Step 3.3: Deep Dive on Selected Ideas

When user selects "deep dive", provide comprehensive inline analysis:

javascript
// For each selected idea, analyze inline
selectedIdeas.forEach(idea => {
  const deepDive = {
    title: idea.title,
    detailed_description: '...',     // Elaborated concept
    technical_requirements: [...],   // Implementation needs
    dependencies: [...],             // What this depends on
    challenges: [                    // Risk/challenge matrix
      { challenge: '...', severity: 'high|medium|low', mitigation: '...' }
    ],
    poc_approach: '...',             // Proof-of-concept suggestion
    success_metrics: [...],          // How to measure success
    source_perspectives: [...]       // Which perspectives contributed
  }
  Write(`${sessionFolder}/ideas/${ideaSlug}.md`, formatIdeaMarkdown(deepDive))
})

##### Step 3.4: Devil's Advocate Challenge

When user selects "challenge", perform inline critical analysis:

javascript
selectedIdeas.forEach(idea => {
  const challenge = {
    idea: idea.title,
    objections: [...],               // 3+ strongest objections
    challenged_assumptions: [...],   // Core assumptions tested
    failure_scenarios: [...],        // When/how this fails
    alternatives: [...],             // Competitive/alternative solutions
    survivability_rating: 1-5,       // How well idea survives challenge
    strengthened_version: '...'      // Improved version post-challenge
  }
  // Record in brainstorm.md
})

##### Step 3.5: Merge Multiple Ideas

When user selects "merge", synthesize inline:

javascript
const merged = {
  title: '...',                     // New merged concept name
  description: '...',              // Unified concept description
  source_ideas: [...],             // Which ideas were merged
  elements_from_each: [...],       // What was taken from each source
  contradictions_resolved: [...],  // How conflicts were handled
  combined_strengths: [...],       // New combined advantages
  implementation_considerations: '...'
}
Write(`${sessionFolder}/ideas/merged-idea-${n}.md`, formatMergedIdeaMarkdown(merged))

##### Step 3.6: Document Each Round

Update brainstorm.md using the Round Documentation Pattern.

Append to Thought Evolution Timeline: User Direction, Decision Log, Ideas Generated/Updated, Analysis Results, Challenged Assumptions, Open Items, Narrative Synthesis.

Replace (not append):

| Section | Update Rule | |---------|-------------| | ## Current Ideas | Overwrite with latest ranked idea list | | ## Table of Contents | Update links to include new Round N sections |

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

javascript
const synthesis = {
  session_id: sessionId,
  topic,
  completed: getUtc8ISOString(),
  total_rounds: roundCount,
  top_ideas: [                    // Top 5 ranked ideas
    {
      title: '...', description: '...',
      source_perspective: '...',
      score: 1-10,                // Final viability score
      novelty: 1-5,              // Innovation rating
      feasibility: 1-5,          // Implementation feasibility
      key_strengths: [...],
      main_challenges: [...],
      next_steps: [...],
      review_status: 'accepted|modified|rejected|pending'
    }
  ],
  parked_ideas: [...],           // Ideas for future consideration
  key_insights: [...],           // Key learnings from brainstorming
  recommendations: {
    primary: '...',              // Best path forward
    alternatives: [...]          // Other viable options
  },
  follow_up: [                   // Suggested next steps
    { type: 'implement|research|validate', summary: '...' }
  ],
  decision_trail: [              // Consolidated from all phases
    { round: 1, decision: '...', context: '...', chosen: '...', reason: '...', impact: '...' }
  ]
}
Write(`${sessionFolder}/synthesis.json`, JSON.stringify(synthesis, null, 2))

##### Step 4.2: Final brainstorm.md Update

Synthesis & Conclusions:

• 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

Current Ideas (Final):

| Subsection | Content | |------------|---------| | Top Ideas | Ranked by score with strengths/challenges | | Idea Evolution | How top ideas developed across rounds | | Key Insights | Valuable learnings for future reference |

Decision Trail:

| Subsection | Content | |------------|---------| | Critical Decisions | Pivotal decisions that shaped the outcome | | Direction Changes | Timeline of scope/focus adjustments with rationale | | Trade-offs Made | Key trade-offs and why certain paths were chosen |

Session Statistics: Total rounds, ideas generated, ideas survived challenges, perspectives used, artifacts generated.

##### Step 4.3: Interactive Top-Idea Review (skip in auto mode)

Batch review of top ideas (max 4 questions per call, so group top ideas accordingly):

javascript
// Update progress
functions.update_plan([{ id: "phase-4", title: "Phase 4: Convergence & Crystallization", status: "in_progress" }])

if (!autoYes) {
  // Batch review: up to 4 ideas per functions.request_user_input call
  const batchSize = 4
  for (let batch = 0; batch < rankedIdeas.length; batch += batchSize) {
    const batchIdeas = rankedIdeas.slice(batch, batch + batchSize)
    const review = functions.request_user_input({
      questions: batchIdeas.map((idea, i) => ({
        header: `Idea #${batch + i + 1}`,   // max 12 chars
        question: `"${idea.title}" (score: ${idea.score}). Your decision:`,
        multiSelect: false,
        options: [
          { label: "Accept", description: "Keep in final recommendations" },
          { label: "Modify", description: "Adjust scope or priority" },
          { label: "Reject", description: "Remove from recommendations" },
          { label: "Accept Rest", description: "Accept all remaining ideas" }
        ]
      }))
    })
    // Process: Accept → "accepted" | Modify → gather text → "modified" | Reject → "rejected"
    // Accept Rest → mark all remaining as "accepted", break outer loop
    // Record review decisions to brainstorm.md Decision Log + update synthesis.json
  }
}

Review Summary (append to brainstorm.md):

markdown
### Top Idea Review Summary
| # | Idea | Score | Novelty | Feasibility | Review Status | Notes |
|---|------|-------|---------|-------------|---------------|-------|
| 1 | [title] | 8 | 4 | 3 | Accepted | |
| 2 | [title] | 7 | 5 | 2 | Modified | [notes] |
| 3 | [title] | 6 | 3 | 4 | Rejected | [reason] |

##### Step 4.4: MANDATORY Terminal Gate (Post-Completion Next Step)

CRITICAL: This gate MUST execute. The workflow MUST NOT end without this functions.request_user_input call.

javascript
// Update progress — mark phase 4 complete, activate terminal gate
functions.update_plan([
  { id: "phase-4", title: "Phase 4: Convergence & Crystallization", status: "completed" },
  { id: "next-step", title: "GATE: Post-Completion Next Step", status: "in_progress" }
])

const nextStep = functions.request_user_input({
  questions: [{
    header: "Next Step",    // max 12 chars
    question: "Brainstorming complete. What would you like to do next?",
    multiSelect: false,
    options: [
      { label: "Execute Task", description: "Build implementation scope and handoff spec from top ideas" },
      { label: "Create Issue", description: "Convert top ideas into trackable issues" },
      { label: "Done", description: "End workflow, all artifacts saved" }
    ]
  }]
})

// Handle next step
if (nextStep === "Execute Task") {
  // Build implementation scope from accepted ideas
  // Step A: Identify scope items from top ideas
  // Step B: Generate handoff-spec.json with implementation details
  // Step C: Write handoff-spec.json to session folder
  Write(`${sessionFolder}/handoff-spec.json`, JSON.stringify({
    session_id: sessionId,
    topic,
    scope_items: acceptedIdeas.map(idea => ({
      title: idea.title,
      description: idea.description,
      implementation_approach: idea.next_steps,
      priority: idea.score >= 8 ? 'high' : idea.score >= 5 ? 'medium' : 'low',
      estimated_complexity: idea.feasibility <= 2 ? 'high' : idea.feasibility <= 4 ? 'medium' : 'low'
    })),
    recommended_workflow: 'workflow-lite-plan or workflow-plan',
    _metadata: { generated: getUtc8ISOString(), source_session: sessionId }
  }, null, 2))
  // Display: "Handoff spec created. Run /workflow-lite-plan to execute."
} else if (nextStep === "Create Issue") {
  // Display command for user to run manually
  // "/issue:from-brainstorm ${sessionFolder}" or "/issue:new ..."
}

// Mark terminal gate complete
functions.update_plan([
  { id: "next-step", title: "GATE: Post-Completion Next Step", status: "completed" }
])

Success Criteria:

• synthesis.json created with complete synthesis
• brainstorm.md finalized with all conclusions
• Terminal gate executed with user's next-step choice
• If "Execute Task": handoff-spec.json created with implementation scope
• Session complete and all artifacts available

Templates

Round Documentation Pattern

Each round follows this structure in brainstorm.md:

markdown
### Round N - [DeepDive|Diverge|Challenge|Merge] (timestamp)

#### User Input
What the user indicated they wanted to focus on

#### Decision Log
<!-- Use Decision Record Format from Recording Protocol -->

#### Ideas Generated
New ideas from this round with ratings

#### Analysis Results
Detailed findings from this round's analysis
- Finding 1 (evidence: file:line or rationale)
- Finding 2 (evidence: file:line or rationale)

#### Challenged Assumptions
- ~~Previous assumption~~ → New understanding
  - Reason: Why the assumption was wrong

#### Open Items
Remaining questions or exploration directions

#### Narrative Synthesis
<!-- Use Narrative Synthesis Format from Recording Protocol -->

brainstorm.md Evolution Summary

• Header: Session ID, topic, start time, dimensions, mode
• Session Context: Focus areas, perspectives, constraints
• Exploration Vectors: Key questions guiding exploration
• Initial Decisions: Why these perspectives and focus areas were selected
• Thought Evolution Timeline: Round-by-round findings
• Round 1: Exploration Results + Decision Log + Narrative Synthesis
• Round 2-N: Current Ideas Summary + User feedback + direction adjustments + new ideas + Decision Log + Narrative Synthesis
• Decision Trail: Consolidated critical decisions across all rounds
• Synthesis & Conclusions: Summary, top ideas, recommendations
• Current Ideas (Final): Consolidated ranked ideas
• Session Statistics: Rounds completed, ideas generated, artifacts produced

Reference

Output Structure

{projectRoot}/.workflow/.brainstorm/BS-{date}-{slug}/
├── brainstorm.md                  # Complete thought evolution timeline
├── exploration-codebase.json      # Phase 2: Codebase context
├── perspectives/                  # Phase 2: Individual perspective outputs
│   ├── creative.json
│   ├── pragmatic.json
│   └── systematic.json
├── perspectives.json              # Phase 2: Aggregated findings with synthesis
├── research.json                  # Phase 2/3: External research findings (if web.run used)
├── synthesis.json                 # Phase 4: Final synthesis
├── handoff-spec.json              # Phase 4: Implementation scope (if "Execute Task" selected)
└── ideas/                         # Phase 3: Individual idea deep-dives
    ├── idea-1.md
    ├── idea-2.md
    └── merged-idea-1.md

| File | Phase | Description | |------|-------|-------------| | brainstorm.md | 1-4 | Session metadata → thought evolution → conclusions | | exploration-codebase.json | 2 | Codebase context: relevant files, patterns, constraints | | perspectives/*.json | 2 | Per-perspective idea generation results | | perspectives.json | 2 | Aggregated findings with cross-perspective synthesis | | research.json | 2-3 | External research: patterns, best practices, inspiration | | ideas/*.md | 3 | Individual idea deep-dives and merged ideas | | synthesis.json | 4 | Final synthesis: top ideas, recommendations, insights | | handoff-spec.json | 4 | Implementation scope and handoff (if Execute Task selected) |

Brainstorm Dimensions

| Dimension | Keywords | Description | |-----------|----------|-------------| | technical | 技术, technical, implementation, code, 实现, architecture | Implementation approaches | | ux | 用户, user, experience, UX, UI, 体验, interaction | User-facing design ideas | | business | 业务, business, value, ROI, 价值, market | Business model innovations | | innovation | 创新, innovation, novel, creative, 新颖 | Breakthrough ideas | | feasibility | 可行, feasible, practical, realistic, 实际 | Realistic approaches | | scalability | 扩展, scale, growth, performance, 性能 | Large-scale solutions | | security | 安全, security, risk, protection, 风险 | Security considerations |

Brainstorm Perspectives

| Perspective | Focus | Best For | |-------------|-------|----------| | Creative | Innovation, cross-domain inspiration, challenging assumptions | Generating novel and surprising ideas | | Pragmatic | Implementation feasibility, effort estimates, blockers | Reality-checking ideas | | Systematic | Problem decomposition, patterns, scalability, architecture | Organizing and structuring solutions |

Brainstorm Modes

| Mode | Intensity | Perspectives | Description | |------|-----------|-------------|-------------| | Creative | High novelty | 1 perspective | Fast, focus on novel ideas | | Balanced | Mixed | 3 perspectives | Moderate, balanced exploration (default) | | Deep | Comprehensive | 3 perspectives + deep refinement | Thorough multi-round investigation |

Collaboration Patterns

| Pattern | Usage | Description | |---------|-------|-------------| | Parallel Divergence | New topic | All perspectives explored serially for comprehensive coverage | | Sequential Deep-Dive | Promising idea | One perspective elaborates, others critique | | Debate Mode | Controversial approach | Inline analysis arguing for/against | | Synthesis Mode | Ready to decide | Inline synthesis combining insights from all perspectives |

Context Overflow Protection

Per-Perspective Limits:

• Main analysis output: < 3000 words
• Sub-document (if any): < 2000 words each
• Maximum sub-documents: 5 per perspective

Synthesis Protection:

• If total analysis > 100KB, synthesis reads only main analysis files (not sub-documents)
• Large ideas automatically split into separate idea documents in ideas/ folder

Recovery Steps:

1. Check outputs for truncation or overflow
2. Reduce scope: fewer perspectives or simpler topic
3. Use structured brainstorm mode for more focused output
4. Split complex topics into multiple sessions

Error Handling

| Situation | Action | Recovery | |-----------|--------|----------| | No codebase detected | Normal flow, pure topic brainstorming | Proceed without exploration-codebase.json | | Codebase search fails | Continue with available context | Note limitation in brainstorm.md | | Web research fails | Continue without external findings | Note in brainstorm.md, rely on inline analysis | | Research conflicts with ideas | Present as competing evidence | Let user decide which direction to pursue | | No good ideas | Reframe problem or adjust constraints | Try new exploration angles | | Perspectives conflict | Present as tradeoff options | Let user select preferred direction | | Max rounds reached (6) | Force synthesis phase | Highlight unresolved questions | | Session folder conflict | Append timestamp suffix | Create unique folder | | User timeout | Save state, show resume command | Use --continue to resume |

Best Practices

Core Principles

1. No code modifications: This skill is strictly read-only. It produces analysis and idea documents but NEVER modifies source code.
2. Record Decisions Immediately: Capture decisions as they happen using the Decision Record format
3. Evidence-Based: Ideas referencing codebase patterns should include file:line evidence
4. Embrace Conflicts: Perspective conflicts often reveal important tradeoffs

Before Starting

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 perspective results 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. Iterate Thoughtfully: Each refinement round should meaningfully advance ideas
5. Track Idea Evolution: Document how ideas changed across rounds

Documentation Practices

1. Timeline Clarity: Use clear timestamps for traceability
2. Evolution Tracking: Document how ideas developed and morphed
3. Multi-Perspective Synthesis: Document convergent/conflicting themes
4. Action Items: Generate specific, implementable recommendations

When to Use

Use brainstorm-with-file when:

• Generating new ideas and solutions for a topic
• Need multi-perspective exploration of possibilities
• Want documented thought evolution showing how ideas develop
• Exploring creative solutions before committing to implementation
• Need diverge-converge cycles to refine ideas

Consider alternatives when:

• Analyzing existing code/architecture → use analyze-with-file
• Specific bug diagnosis needed → use debug-with-file
• Complex planning with requirements → use collaborative-plan-with-file
• Ready to implement → use lite-plan

Now start brainstorming for topic: $TOPIC

IMPORTANT: This skill is brainstorming-only. It produces analysis, perspectives, and synthesis documents but NEVER executes code, modifies source files, or auto-launches other skills. All follow-up actions require user to manually run the suggested commands.