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

# 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

> **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:

### 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

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):

// 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):

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

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

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:

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

// 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.

// 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

// 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:"

// 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:

// 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:

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:

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

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):

// 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):

### 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.

// 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:

### 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.