---
name: brainstorm-workflows
description: "Detailed 3-phase workflow for sp:brainstorm - Input, Ideation, Output with delegation pointers"
---

# Brainstorm 3-Phase Workflow

Detailed guidance for the sp:brainstorm ideation workflow.

## Phase 1: Input Processing

**Goal:** Parse and validate input, extract context

### Input Type Detection

```
IF input contains "/" or "\" AND ends with ".md":
    → Treat as file path
ELSE:
    → Treat as issue description
```

### Reading Task Files

When a file path is detected:

1. **Resolve path** — Convert relative paths to absolute
2. **Read content** — Use Read tool
3. **Parse frontmatter** — Extract YAML fields:
   - `status`: Current task status
   - `wbs`: Work breakdown structure number
   - `name`: Task identifier
   - `description`: Brief summary
4. **Extract sections** — Parse markdown body:
   - Background context
   - Requirements
   - Existing solutions (if any)

### Validation Checklist

- [ ] Input is not empty
- [ ] File exists (if path provided)
- [ ] YAML frontmatter is valid
- [ ] Required fields present
- [ ] Content has meaningful length (>50 characters)

### Clarification via AskUserQuestion

**When to clarify:**
- Input < 20 characters
- Background section empty or missing key context
- Requirements vague or incomplete
- Technical terms undefined
- Multiple valid interpretations

**Example:**
```yaml
AskUserQuestion:
  - question: "What type of authentication do you need?"
    header: "Auth Type"
    options:
      - label: "JWT tokens"
        description: "Stateless, good for APIs, requires careful key management"
      - label: "Session-based"
        description: "Server-managed, simpler, good for traditional web apps"
      - label: "OAuth2/OIDC"
        description: "Third-party login (Google, GitHub), more complex setup"
    multiSelect: false
```

---

## Phase 2: Ideation (Delegated)

**Goal:** Generate 2-3 solution approaches with trade-offs

### Research Delegation

DO NOT implement research directly. Delegate to specialized skills:

```
1. Invoke sp:source-driven-development for verification
   - Use for any external claims
   - Follow source-first protocol

2. Delegate research + synthesis inline by default
   - Run in the current session; escalate to `spur agent run` only on a subprocess trigger
   - Request confidence scoring
```

### Approach Generation

**Structure:**
```markdown
### Approach 1: [Descriptive Name] ⭐ Recommended

**Description:** 2-3 sentences explaining the approach

**Trade-offs:**
- **Pros:**
  - Advantage 1
  - Advantage 2
- **Cons:**
  - Disadvantage 1
  - Disadvantage 2

**Implementation Notes:**
- Key technical considerations
- Dependencies or prerequisites

**Confidence:** HIGH/MEDIUM/LOW
**Sources:** [Citations with dates]
```

### Source Citation Format

```markdown
**Sources:**
- [Title](URL) | **Verified**: YYYY-MM-DD
- [Title](URL) | **Verified**: YYYY-MM-DD
```

### Confidence Scoring

| Level | Range | Criteria |
|-------|-------|----------|
| **HIGH** | >90% | Direct quote from official docs (2025+) |
| **MEDIUM** | 70-90% | Synthesized from multiple sources |
| **LOW** | <70% | Uncertain, flag for review |

---

## Phase 3: Structured Output

**Goal:** Format and deliver results

### Section Generation

1. **Overview** (100-150 words)
   - Context and problem summary
   - Why this matters
   - Current state

2. **Approaches** (200-300 words each)
   - 2-3 options with trade-offs
   - Implementation considerations
   - Confidence levels

3. **Recommendations** (100-150 words)
   - Recommended approach with reasoning
   - Key factors in decision
   - When to consider alternatives

4. **Next Steps** (bulleted list)
   - Potential task items
   - Research needs
   - Implementation prerequisites

### Output Template

```markdown
# Brainstorm: [Topic]

**Date:** YYYY-MM-DD

## Overview

[Context and problem summary]

## Approaches

### Approach 1: [Name] ⭐ Recommended

**Description:** [2-3 sentences]

**Trade-offs:**
- **Pros:**
  - [Advantage 1]
- **Cons:**
  - [Disadvantage 1]

**Implementation Notes:**
- [Technical considerations]

**Confidence:** HIGH/MEDIUM/LOW
**Sources:** [Citations]

### Approach 2: [Name]

[Same structure]

## Recommendations

[Recommended approach with reasoning]

## Next Steps

1. [Task item 1]
2. [Task item 2]

---

**Generated by:** sp:brainstorm
**Research delegation:** sp:source-driven-development, spur agent run
```

---

## Task Creation Delegation

When user confirms approach, delegate to sp:spur-dev:

```
// Pseudocode: Delegate breakdown to sp:spur-dev
Skill(skill="sp:spur-dev", args="plan <recommended_approach>")

// Receive structured JSON output, then create tasks via sp:spur-cli
Bash: spur task batch-create --file decomposition.json   # bare JSON array (see sp:spur-cli)
```

### Task Extraction Criteria

**Task-worthy:**
- Concrete and executable
- Clear completion condition
- Can be assigned to someone
- Estimated effort >30 minutes

**Not task-worthy:**
- "Consider performance implications" (too vague)
- "Research options" (already done)

---

## Error Handling

| Error | Action |
|-------|--------|
| Empty input | Prompt for issue description or file path |
| File not found | Provide clear error with path |
| Invalid YAML | Report parsing error |
| Missing fields | List missing fields, ask if incomplete |
| Research unavailable | Continue, note reduced confidence |
| Save fails | Display output, suggest manual save |

---

## Graceful Degradation

When tools unavailable:

1. **Continue** with available tools
2. **Note** reduced confidence
3. **Suggest** manual fallback
4. **Save** intermediate state