brainstorming

# Brainstorming v2.0: Resilient Multi-Model Planning

Turn ideas into validated designs through collaborative AI dialogue with resilient model execution and confidence-based validation.

## Overview

This skill improves upon v1.0 by addressing critical reliability gaps:

**Key v2.0 Improvements:**
- **No AskUserQuestion dependency**: Uses Task + Tasks for structured interaction
- **Fallback chains**: 3+ models per role ensures completion even if some fail
- **Explicit parallelism**: Documented Task call patterns for parallel execution
- **Defined algorithms**: Consensus matrix and confidence scoring are mathematically specified

## When to Use

Use this skill BEFORE implementing any feature:
- "Design a user authentication system"
- "Brainstorm approaches for API rate limiting"
- "Plan architecture for a new dashboard feature"
- "Evaluate options for real-time data synchronization"

## Prerequisites

### Required Setup

```bash
# 1. Install required skills
/plugin marketplace add MadAppGang/claude-code
skill install superpowers:using-git-worktrees
skill install superpowers:writing-plans

# 2. Verify OpenRouter access (for multi-model)
export OPENROUTER_API_KEY=your-key

# 3. Configure models in ~/.claude/settings.json
{
  "brainstorming": {
    "primary_model": "anthropic/claude-opus-4-20250514",
    "explorer_models": [
      "x-ai/grok-code-fast-1",
      "google/gemini-2-5-pro",
      "anthropic/claude-sonnet-4-20250514"
    ]
  }
}
```

### Model Requirements

| Role | Min Context | Capabilities |
|------|-------------|--------------|
| Primary | 200K tokens | Complex reasoning, orchestration |
| Explorer | 100K tokens | Code generation, analysis |

## Workflow

### Phase 0: Problem Analysis (200-300 words)

**Objective**: Capture problem scope, constraints, and success criteria

**How to Ask Users (Without AskUserQuestion)**:

```typescript
// Pattern: Use Tasks to track questions, Read/Write for presentation

// 1. Write question to temp file
await Write({
  file_path: "/tmp/brainstorm-q1.md",
  content: `## Question 1 of 3

**What are the main constraints or requirements for this feature?**

Please respond with:
- Functional requirements (what it must do)
- Non-functional requirements (performance, scale)
- Any existing dependencies or integrations
`
});

// 2. Present file and wait for user response
// User reads file, provides input via conversation

// 3. Summarize understanding
const problemSummary = await Write({
  file_path: "/tmp/brainstorm-problem.md",
  content: `## Problem Understanding

**Constraints identified:**
- [From user response]

**Success criteria:**
- [Measurable outcomes]

**Scope boundaries:**
- [What's in/out]

---

**Does this accurately capture the problem?** (Reply "yes" to proceed or clarify)
`
});
```

**Gate Type**: USER_GATE (requires confirmation)

---

### Phase 1: Parallel Exploration

**Objective**: Generate diverse solutions via multi-model brainstorming

**Fallback Chain Implementation**:

```typescript
interface ModelResult {
  model: string;
  success: boolean;
  output?: string;
  error?: string;
}

async function exploreWithFallback(
  prompt: string,
  role: "explorer"
): Promise<ModelResult> {
  const fallbackModels = role === "explorer"
    ? ["x-ai/grok-code-fast-1", "google/gemini-2-5-pro", "deepseek/deepseek-coder"]
    : ["anthropic/claude-opus-4-20250514", "anthropic/claude-sonnet-4-20250514"];

  for (const model of fallbackModels) {
    try {
      const result = await Task({
        model: model,
        prompt: prompt,
        timeout_ms: 120000  // 2 minute timeout
      });

      return { model, success: true, output: result };
    } catch (error) {
      console.warn(`Model ${model} failed:`, error.message);
      continue;  // Try next in chain
    }
  }

  throw new Error(`All models in fallback chain failed`);
}
```

**Parallel Execution Pattern**:

```typescript
// WRONG: Sequential (slow)
// const result1 = await Task({ model: "grok", ... });
// const result2 = await Task({ model: "gemini", ... });
// const result3 = await Task({ model: "sonnet", ... });

// CORRECT: Parallel (3-5x faster)
const [result1, result2, result3] = await Promise.all([
  Task({
    model: "x-ai/grok-code-fast-1",
    prompt: generateExplorerPrompt(problem, "fast_code")
  }),
  Task({
    model: "google/gemini-2-5-pro",
    prompt: generateExplorerPrompt(problem, "balanced")
  }),
  Task({
    model: "anthropic/claude-sonnet-4-20250514",
    prompt: generateExplorerPrompt(problem, "thorough")
  })
]);

// Handle partial failures
const results = [result1, result2, result3].filter(r => r.success);
if (results.length === 0) {
  throw new Error("All exploration models failed");
}
```

**Output Format**:
```markdown
## Approach: [Name]

**Model**: [Which model generated this]
**Approach Type**: [architecture/algorithm/pattern]
**Summary**: 2-3 sentences

**Key Components**:
1. Component A
2. Component B
3. Component C

**Trade-offs**:
- + Advantage
- - Disadvantage

**Confidence**: [Model's confidence 0-100]
```

**Gate Type**: AUTO_GATE (automatic consolidation)

---

### Phase 2: Consensus Analysis

**Objective**: Identify strongest ideas using defined algorithms

**Consensus Matrix Algorithm**:
1. **Clustering**: Group approaches by semantic similarity (vector embedding + clustering)
2. **Scoring**: Count model agreement per cluster
3. **Classification**: UNANIMOUS (3/3), STRONG (2/3), DIVERGENT (1/3)
4. **Confidence**: Weighted average of model confidences + agreement bonus

**Consensus Matrix Calculation**:

```typescript
interface Approach {
  id: string;
  name: string;
  summary: string;
  model: string;  // Which model proposed
  modelConfidence: number;  // 0-100
  embedding: number[];  // For clustering
}

interface Cluster {
  approaches: Approach[];
  representative: Approach;  // Most complete
  agreementScore: number;  // 0-1
  confidenceScore: number;  // 0-100
  consensusLevel: "UNANIMOUS" | "STRONG" | "DIVERGENT";
}

function calcu