doing-a-simple-two-stage-fanout_skill

Overview

This skill orchestrates a simple two-stage fan-out analysis for corpora that exceed a single agent's effective context. It splits the corpus across parallel Worker subagents, routes Worker outputs to Critic subagents for independent reviews, and then synthesizes everything with a single Summarizer while tracking tasks and handling failures. The workflow produces explicit files and an auditable orchestration plan before any work begins.

How this skill works

The skill computes a layout (segments, Workers, Critics) from corpus size and an effort-level choice, creates a temp workspace with absolute paths, and writes a plan that includes a fan-out diagram and assignment tables. It then creates tasks for every Worker, Critic, and the Summarizer, launches Workers in parallel, verifies outputs, launches Critics in parallel, verifies outputs again, and finally runs the Summarizer to produce the final report. Built-in failure recovery handles context-limit splits, missing outputs, and stuck agents.

When to use it

• Analyzing large text, code, or data collections that exceed one agent's context window
• When you want redundant independent reviews of each segment to reduce missed items
• When you need an auditable, file-backed orchestration with explicit task dependencies
• When you need a repeatable pipeline that can recover from agent failures
• When you want a short, controlled burst of parallelism rather than continuous streaming

Best practices

• Confirm the analysis goal and choose an effort level before computing the layout
• Provide file paths so token estimates can be calculated with wc -c or the bundled script
• Always use absolute paths in prompts and plan documents
• Create all tasks and dependencies up front; do not launch subagents until the plan is approved
• Use the split-on-failure rules (append a/b) for context-limit problems rather than blind retries

Example use cases

• Codebase review: split thousands of source files into segments, detect patterns and hotspots
• Literature survey: analyze a large corpus of papers, have critics flag gaps, then synthesize findings
• Log analysis: partition massive log archives for parallel anomaly detection and consolidated reporting
• Policy audit: run independent critics on each policy segment to surface contradictions before final summary