fan-out

name	fan-out
description	| Use when this capability is needed.

Fan-Out

Some tasks are embarrassingly parallel - researching 5 APIs, analyzing 10 files, testing 3 approaches. Running them sequentially wastes time. This elixir orchestrates parallel execution: decompose work, fan out to agents, collect and synthesize results.

When To Activate

Trigger when:

• Task involves analyzing multiple independent items
• Research spans several unrelated topics
• Need to explore multiple approaches simultaneously
• Batch processing with no inter-item dependencies
• User says "check all of these" or "investigate each"

Do NOT trigger for:

• Sequential tasks where B depends on A
• Single-item deep analysis
• Tasks requiring context accumulation across items
• When parallel execution would overwhelm system resources

The Pattern

                    ┌──→ [Agent 1] ──→ Result 1 ──┐
                    │                              │
[Task] → Decompose ─┼──→ [Agent 2] ──→ Result 2 ──┼──→ Aggregate → [Final]
                    │                              │
                    └──→ [Agent 3] ──→ Result 3 ──┘

Instructions

Step 1: Validate Parallelizability

Confirm the task is fan-out appropriate:

Subtask independence check:
- Can subtask B complete without subtask A's result? [YES/NO]
- Do subtasks share mutable state? [YES/NO - should be NO]
- Is order of completion irrelevant? [YES/NO - should be YES]

If any check fails → Use 'pipeline' pattern instead

Step 2: Decompose the Task

Break work into discrete, independent units:

Original task: [Description]

Subtasks:
1. [Subtask 1] - Agent type: [explore/research/analyze]
2. [Subtask 2] - Agent type: [explore/research/analyze]
3. [Subtask 3] - Agent type: [explore/research/analyze]
...

Expected outputs:
- Subtask 1 → [What result looks like]
- Subtask 2 → [What result looks like]

Step 3: Spawn Parallel Agents

Launch agents simultaneously:

Spawning [N] parallel agents:

Agent 1: [Subtask description]
Agent 2: [Subtask description]
Agent 3: [Subtask description]

[Wait for all to complete]

Use Task tool with appropriate subagent_type for each.

Step 4: Collect Results

Gather outputs from all agents:

Results received:
- Agent 1: [Summary]
- Agent 2: [Summary]
- Agent 3: [Summary]

Step 5: Synthesize

Aggregate results into coherent output:

Synthesis:
- [Combined insight 1]
- [Combined insight 2]
- [Patterns across results]
- [Conflicts or contradictions]

Step 6: Report

Present unified findings:

## Fan-Out Results: [Task]

### Summary
[High-level findings]

### Details by Subtask
1. [Subtask 1 findings]
2. [Subtask 2 findings]
...

### Cross-Cutting Insights
[Patterns that emerged across subtasks]

### Recommendations
[Actionable next steps]

Resource Management

**Agent limits:** - Recommended max: 5 parallel agents - Hard limit: Based on system capacity

When to limit parallelism:

• Complex subtasks → fewer agents (3 max)
• Simple lookups → more agents (5+)
• Resource-intensive work → sequential fallback

Failure handling:

• If agent fails: Log error, continue with others
• If >50% fail: Abort and report
• Partial results: Clearly mark incomplete

NEVER

• Fan out dependent tasks (use pipeline instead)
• Spawn more agents than subtasks warrant
• Ignore failed agents - always report what succeeded/failed
• Assume all results are equally valid without synthesis
• Fan out trivial tasks (overhead not worth it)

ALWAYS

• Verify independence before fanning out
• Define clear, specific prompts for each agent
• Set expectations for what each agent should return
• Synthesize results, don't just concatenate
• Report which subtasks succeeded/failed

Examples

Example 1: Multi-File Analysis

User: "Check all our API endpoints for authentication issues"

Subtask independence check:
- Can each file be analyzed independently? YES
- Shared state? NO
- Order irrelevant? YES

→ Fan-out appropriate

Decomposing:
1. Analyze src/api/users.ts for auth issues
2. Analyze src/api/orders.ts for auth issues
3. Analyze src/api/products.ts for auth issues
4. Analyze src/api/admin.ts for auth issues

[Spawns 4 parallel explore agents]

Results:
- users.ts: Missing rate limiting on login endpoint
- orders.ts: No auth check on order history
- products.ts: Clean
- admin.ts: Using deprecated auth method

Synthesis:
3 of 4 files have auth issues. Most critical: orders.ts
exposes user data without authentication.

Example 2: Research Multiple Technologies

User: "Compare Redis, Memcached, and DynamoDB for our caching layer"

Subtask independence check:
- Independent research? YES
- Shared state? NO
- Order irrelevant? YES

→ Fan-out appropriate

Decomposing:
1. Research Redis: features, performance, pricing
2. Research Memcached: features, performance, pricing
3. Research DynamoDB: features, performance, pricing

[Spawns 3 parallel research agents]

Results synthesized into comparison table with
cross-cutting analysis of trade-offs.

Example 3: Not Appropriate for Fan-Out

User: "Build a feature: first design it, then implement, then test"

Subtask independence check:
- Can implementation happen without design? NO
- Can tests run without implementation? NO

→ NOT fan-out appropriate
→ Use 'pipeline' pattern instead

What DOESN'T work: - Fanning out dependent tasks: Results are incoherent, agents make conflicting assumptions - Too many agents: System overwhelmed, diminishing returns - Vague agent prompts: Results are too varied to synthesize - No synthesis step: User gets disconnected bullet points, not insight

Why This Elixir Exists

Sequential processing of independent tasks wastes time. A human would delegate parallel work to multiple people. This elixir gives Claude the same capability: decompose, distribute, synthesize.

The key insight: parallelism only helps when tasks are truly independent. Otherwise, you get chaos, not speed.

---

Converted and distributed by TomeVault — claim your Tome and manage your conversions.