tomevault-io Fan-Out
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
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
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.