Codex Brainstorm-With-File Prompt Skill

Codex Brainstorm-With-File Prompt

Overview

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

Core workflow: Seed Idea → Expand → Multi-Perspective Explore → Synthesize → Refine → Crystallize

Key features:

brainstorm.md: Complete thought evolution timeline
Multi-perspective analysis: Creative + Pragmatic + Systematic (serial, inline)
Idea expansion: Progressive questioning and exploration
Diverge-Converge cycles: Generate options then focus on best paths

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-{slug}-{YYYY-MM-DD}

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-{slug}-{date}
   └─ Create session folder (or detect existing → continue mode)

Step 1: Seed Understanding
   ├─ Parse topic, identify brainstorm dimensions
   ├─ Role/perspective selection with user (or auto)
   ├─ Initial scoping (mode, focus areas, 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
   ├─ Aggregate findings → perspectives.json
   ├─ Update brainstorm.md with Round 1
   └─ Initial Idea Coverage Check

Step 3: Interactive Refinement (Multi-Round, max 6)
   ├─ Present current ideas and perspectives
   ├─ Gather user feedback
   ├─ 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
   │   └─ 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
   ├─ Interactive Top-Idea Review (per-idea confirm/modify/reject)
   └─ Offer options: show next-step commands / export / done

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 = Bash('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-${slug}-${dateStr}`
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
Bash(`mkdir -p ${sessionFolder}`)

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:

Auto mode: Select top 3 recommended professional roles based on keyword matching
Manual mode: Present recommended roles + "Use simple perspectives" option
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) {
  // 1. Brainstorm Mode (single-select)
  const mode = request_user_input({
    questions: [{
      header: "Brainstorm Mode",
      id: "mode",
      question: "Select brainstorming intensity:",
      options: [
        { label: "Creative Mode", description: "Fast, high novelty, 1 perspective" },
        { label: "Balanced Mode(Recommended)", description: "Moderate, 3 perspectives" },
        { label: "Deep Mode", description: "Comprehensive, 3 perspectives + deep refinement" }
      ]
    }]
  })

  // 2. Focus Areas (multi-select)
  const focusAreas = request_user_input({
    questions: [{
      header: "Focus Areas",
      id: "focus",
      question: "Select brainstorming focus:",
      options: generateFocusOptions(dimensions) // Dynamic based on dimensions
    }]
  })

  // 3. Constraints (multi-select)
  const constraints = request_user_input({
    questions: [{
      header: "Constraints",
      id: "constraints",
      question: "Any constraints to consider?",
      options: [
        { label: "Existing Architecture", description: "Must fit current system" },
        { label: "Time Constraints", description: "Short implementation timeline" },
        { label: "Resource Constraints", 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:

Core question: What is the fundamental problem/opportunity?
User perspective: Who benefits and how?
Technical angle: What enables this technically?
Alternative approaches: What other ways could this be solved?
Challenges: What could go wrong or block success?
Innovation angle: What would make this 10x better?
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 = Bash(`
  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

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

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

if (!autoYes) {
  const feedback = request_user_input({
    questions: [{
      header: "Brainstorm Direction",
      id: "direction",
      question: `Brainstorm round ${round}: What would you like to do next?`,
      options: [
        { 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" },
        { label: "Ready to Converge", description: "Sufficient ideas, proceed to synthesis" }
      ]
    }]
  })
}

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

Walk through top ideas one-by-one (ordered by score):

for (const [index, idea] of rankedIdeas.entries()) {
  const review = request_user_input({
    questions: [{
      header: `Idea #${index + 1}`,
      id: `idea_${index + 1}`,
      question: `Idea #${index + 1}: "${idea.title}" (score: ${idea.score}, novelty: ${idea.novelty}, feasibility: ${idea.feasibility}). Your decision:`,
      options: [
        { label: "Accept(Recommended)", description: "Keep this idea in final recommendations" },
        { label: "Modify", description: "Adjust scope, description, or priority" },
        { label: "Reject", description: "Remove from final recommendations" }
      ]
    }]
  })
  // Accept → "accepted" | Modify → gather text → "modified" | Reject → gather reason → "rejected"
  // Accept All Remaining → mark all remaining as "accepted", break loop
  // Record review decision 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: Post-Completion Options

Available Options (this skill is brainstorming-only — NEVER auto-launch other skills):

| Option | Purpose | Action | |--------|---------|--------| | Show Next-Step Commands | Show available commands | Display command list for user to manually run | | Export Report | Generate shareable report | Create formatted report document | | Done | No further action | End workflow |

Next-step commands to display (user runs manually, NOT auto-launched):

/workflow-lite-plan "..." → Generate implementation plan
/issue:new "..." → Track top ideas as issues
/workflow:analyze-with-file "..." → Analyze top idea in detail

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

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-{slug}-{date}/
├── 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
├── synthesis.json                 # Phase 4: Final synthesis
└── 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 | | ideas/*.md | 3 | Individual idea deep-dives and merged ideas | | synthesis.json | 4 | Final synthesis: top ideas, recommendations, insights |

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:

Check outputs for truncation or overflow
Reduce scope: fewer perspectives or simpler topic
Use structured brainstorm mode for more focused output
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 | | 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

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

Before Starting

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

During Brainstorming

Review Perspectives: Check all perspective results before refinement rounds
Document Assumptions: Track what you think is true for correction later
Use Continue Mode: Resume sessions to build on previous exploration
Iterate Thoughtfully: Each refinement round should meaningfully advance ideas
Track Idea Evolution: Document how ideas changed across rounds

Documentation Practices

Timeline Clarity: Use clear timestamps for traceability
Evolution Tracking: Document how ideas developed and morphed
Multi-Perspective Synthesis: Document convergent/conflicting themes
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.

Agent Skills: Codex Brainstorm-With-File Prompt

Install this agent skill to your local

Skill Files