---

name: fanout description: This skill should be used for multi-perspective analysis through parallel copilot sessions. Triggers include "analyze from multiple angles", "what are the gaps/patterns/friction", "explore before deciding", pre-refactor landscape mapping, or skill/architecture auditing. Each agent gets a DIFFERENT prompt, results aggregated.

fanout

multi-perspective analysis through parallel copilot sessions. each agent gets a DIFFERENT prompt, results aggregated.

philosophy

when to use

decision tree: fanout vs other skills

CopyWhat kind of multi-agent work?
├── Same prompt to different models for consensus?
│   └── use pair --group (gemini + sonnet + codex same question)
├── Different prompts for diverse analysis?
│   └── use FANOUT (gap + pattern + friction + synergy)
├── Orchestrating multiple skills in sequence?
│   └── use skill-compose
├── Discovering and executing work items?
│   └── use auto (ideation → spawn)
├── Single consultation or delegation?
│   └── use pair (consult/delegate/review modes)
└── Long autonomous session with checkpoints?
    └── use loop

decision tree: analysis type selection

CopyWhat analysis perspectives needed?
├── Understanding existing patterns?
│   └── pattern-extraction template
├── Finding missing capabilities?
│   └── gap-analysis template
├── Identifying pain points?
│   └── friction-analysis template
├── Mapping connections between things?
│   └── synergy-mapping template
├── Auditing against platform capabilities?
│   └── platform-audit template
├── Meta-level reflection on approach?
│   └── meta-analysis template
└── Custom analysis?
    └── create ad-hoc prompt with output contract

decision tree: session count

CopyHow many parallel sessions?
├── Deep dive on single topic?
│   └── 2-3 sessions (focused perspectives)
├── Broad landscape analysis?
│   └── 4-6 sessions (comprehensive coverage)
├── Resource constrained?
│   └── 2-3 sessions (prioritize highest value)
├── Exploratory/unknown scope?
│   └── 3-4 sessions (balanced coverage)
└── Follow-up to prior fanout?
    └── 1-2 sessions (fill specific gaps)

workflow

phase 1: scope and select

1. identify analysis target (codebase, skill, architecture, etc.)
2. select 3-6 analysis templates based on goal
3. customize templates if needed (target-specific context)

phase 2: spawn parallel sessions with --await

Copy# Generate parent ID for this fanout operation
FANOUT_ID="fanout-$(date +%Y%m%d-%H%M%S)-$(openssl rand -hex 4)"

# Build prompts with output contracts
for TEMPLATE in gap pattern friction synergy platform meta; do
  cat templates/${TEMPLATE}-analysis.md | \
    sed "s/\$TARGET/$TARGET/" > /tmp/${TEMPLATE}.md
done

# Spawn all sessions in parallel with --await --parent --timeout
# Each runs in background, awaits completion, writes result
for TEMPLATE in gap pattern friction synergy platform meta; do
  (
    RESULT=$(cat /tmp/${TEMPLATE}.md | \
      agents session start -a copilot -p $PROJECT \
        -g "${TEMPLATE}: $TARGET" \
        --parent "$FANOUT_ID" \
        --timeout 120 \
        --await \
        --json -q)
    echo "$RESULT" >> /tmp/results.jsonl
  ) &
done

# Wait for all background jobs
wait

Key flags:

• --await - blocks until session completes, returns output inline
• --parent $FANOUT_ID - links all sessions for hierarchy queries
• --timeout 120 - auto-kill after 120s (prevents runaway sessions)

phase 3: validate and filter results

Copy# Filter successful results (--await returns combined session + await data)
jq -c 'select(.await.status == "completed")' /tmp/results.jsonl > /tmp/valid.jsonl

# Check for failures
FAILED=$(jq -c 'select(.await.status != "completed")' /tmp/results.jsonl | wc -l)
if [ "$FAILED" -gt 0 ]; then
  echo "Warning: $FAILED sessions failed or timed out"
fi

# Query all child sessions via parent hierarchy
agents session list --json -q | \
  jq -r --arg parent "$FANOUT_ID" '.[] | select(.parent_session_id == $parent)'

phase 4: aggregate and synthesize

1. parse all output contracts from valid results
2. extract key findings from each perspective
3. identify patterns across analyses (repeated themes)
4. surface contradictions (where perspectives conflict)
5. synthesize actionable recommendations

output contract (reused from pair)

all fanout agents MUST return this structure:

Copy{
  "mode": "fanout",
  "analysis_type": "gap | pattern | friction | synergy | platform | meta | custom",
  "status": "success | partial | blocked | failed",
  "summary": "50-200 words",
  "confidence": 8,
  "artifacts": [
    {
      "type": "analysis",
      "content": "structured findings"
    }
  ],
  "sources": {
    "files_read": ["path/to/file.ts:10-50"],
    "tools_used": ["layer", "outline", "grep"]
  },
  "assumptions": ["assumption that could affect correctness"],
  "next_steps": ["recommended follow-up"],
  "blockers": []
}

CRITICAL constraint: fanout analysis agents must NOT:

• modify files
• create commits
• write to disk (except output contract)
• execute side effects

analysis templates

see templates/ directory for full prompt templates.

aggregation patterns

theme extraction

Copycollect: all artifact.content from results
group by: repeated concepts/recommendations
output: ranked themes by frequency + confidence-weighted

contradiction surfacing

Copyfor each pair of results:
  compare: recommendations in next_steps
  identify: conflicting advice
  note: confidence scores of each
output: conflicts with context for resolution

confidence-weighted synthesis

Copyfor each recommendation across all results:
  weight = confidence * (1 if status=success else 0.5)
  accumulate weights per unique recommendation
output: recommendations sorted by accumulated weight

concrete values

sourcing legend: heuristic = based on practical experience, not formal research; empirical = measured from actual tool usage; convention = widely adopted standard

integration with agents CLI

Copy# Start trace for fanout run
export AGENTS_TRACE_ID=$(agents report start "fanout: $TARGET" --agent claude --json -q | jq -r '.traceId')

# Report progress as sessions complete
agents report progress "3/6 analyses complete" --confidence 7

# Report completion with synthesis (gist captures multi-perspective analysis)
agents report complete "fanout synthesis ready: 6 perspectives, 12 recommendations" --confidence 9 --gist

# If blocked
agents report blocked "2 sessions timed out" --blocker-type error

session spawning pattern

IMPORTANT: use agents session start NOT direct copilot calls.

Copy# Correct: --await blocks until completion, returns output inline
RESULT=$(cat prompt.md | agents session start -a copilot -p $PROJECT \
  -g "analysis" \
  --parent "$FANOUT_ID" \
  --timeout 120 \
  --await \
  --json -q)

# Result contains both session info and await output:
# { "session_id": "...", "await": { "status": "completed", "output": "..." } }
STATUS=$(echo "$RESULT" | jq -r '.await.status')
OUTPUT=$(echo "$RESULT" | jq -r '.await.output')

# Wrong: no tracking, no parent correlation, loses result
copilot -p --model gemini-3-pro "prompt"

error handling

anti-patterns

composition with other skills

fanout → pair

Copy1. fanout: multi-perspective analysis
2. synthesize findings
3. pair consult: validate synthesis with human or senior model
4. pair delegate: implement selected recommendations

ask-deep → fanout

Copy1. ask-deep: clarify scope and priorities
2. fanout: deep analysis from multiple angles
3. synthesize: present findings
4. ask-deep review: validate findings with user

fanout → loop

Copy1. fanout: landscape analysis before work
2. synthesize: prioritized action items
3. loop: autonomous implementation with findings as context

template summaries

all templates include: <role>, <context>, <task>, <constraints> (READ-ONLY), and <output_contract> (JSON)

reference summaries

tool integration

trails integration

fanout uses agents report which handles trails internally:

Copy# Start fanout trace
export AGENTS_TRACE_ID=$(agents report start "fanout: $TARGET" --agent claude --json -q | jq -r '.traceId')

# Progress updates
agents report progress "4/6 analyses complete" --confidence 7

# Complete with synthesis (gist for permanent artifact)
agents report complete "fanout: $COUNT perspectives, $RECS recommendations" --confidence 9 --gist

# Query fanout history
trails trail replay --format json | jq '.[] | select(.task | contains("fanout"))'

trails enables:

• tracking analysis patterns over time
• measuring session success/timeout rates
• correlating fanout findings with implementation outcomes

tooling requirements

references

• templates/gap-analysis.md - capability gap detection
• templates/pattern-extraction.md - existing pattern discovery
• templates/friction-analysis.md - pain point surfacing
• templates/synergy-mapping.md - connection identification
• templates/platform-audit.md - tool utilization review
• templates/meta-analysis.md - approach reflection
• references/prompt-design.md - effective prompt construction
• references/aggregation.md - synthesis algorithms
• references/failure-modes.md - common issues and fixes