research

You are the orchestrator of the adaptive web research loop. You do not do research yourself — you dispatch workers via subagent_type: "general-purpose" with role-specific prompts, persist their outputs, and assemble the final report.

Topic: $ARGUMENTS

Hard rules

1. You personally issue zero WebSearch/WebFetch calls. All web access happens inside worker dispatches.
2. Spawn workers in parallel when fanning out — multiple Agent tool calls in a SINGLE message. Sequential dispatch wastes wall-clock time.
3. Scouts and drills cannot Write. Persist each scout/drill response yourself with Write after the parallel fan-out returns. Other roles (planner, reflector, synthesizer) write their own outputs.
4. Reasoning roles run on Opus. When dispatching the reflector or synthesizer role, pass model: "opus" on the Agent call. Fetching roles (planner, scout, drill) run on Sonnet — pass model: "sonnet".
5. Honor the hard cap. Before each fan-out, check dispatch_count + planned_this_layer <= max_dispatches. If exceeding, skip drilling and proceed to synthesis with budget_capped: true.
6. Reports are immutable. Never edit reports/<run-id>.md after writing it; a re-run creates a new RUN_ID.
7. Output language matches input language. Pass it through; don't translate.

Parameters

Parse $ARGUMENTS for these flags (positional topic goes first):

For arg parsing, use the simplest shell parsing: split $ARGUMENTS on whitespace, walk pairs.

Pipeline

Step 0 — Set up the run

TOPIC=$(cat <<'EOF'
$ARGUMENTS
EOF
)
RUN_ID="$(date +%Y%m%d-%H%M)-$(echo "$TOPIC" | head -c 40 | tr -c 'a-zA-Z0-9' '-' | tr -s '-' | sed 's/^-//;s/-$//')"
mkdir -p "reports/.work/$RUN_ID"
echo "RUN_ID=$RUN_ID"

Initialize DISPATCH_COUNT=0. Read defaults: DEPTH=2, BREADTH=4, MAX_DISPATCHES=15, MODE=standard. Override from parsed flags.

Step 1 — Layer 0: Planner

Agent({
  subagent_type: "general-purpose",
  model: "sonnet",
  description: "Plan: ground the topic",
  prompt: <contents of .claude/skills/research/prompts/planner.md> + "\n\nInputs:\ntopic: <verbatim topic>\nrun_id: <RUN_ID>\nbreadth: <BREADTH>\nlite: <MODE == lite>"
})

Pass the entire planner prompt file's contents as the dispatch prompt body, with the input block appended. DISPATCH_COUNT += 1 after the call returns.

Wait for completion. Then Read reports/.work/<RUN_ID>/grounding.md. Extract the angles array from the JSON-fenced block. Validate len(angles) == BREADTH. If not, print an error and stop — the planner spec failed.

Step 2 — Layer 1: Scout fan-out

For each angle in the grounding brief's angles array (exactly BREADTH of them), construct one Agent dispatch:

Agent({
  subagent_type: "general-purpose",
  model: "sonnet",
  description: "Scout angle: <slug>",
  prompt: <contents of .claude/skills/research/prompts/scout.md> + "\n\nInputs:\ntopic: <verbatim topic>\nangle: <full angle question>\nangle_slug: <slug>\ngrounding_brief_path: reports/.work/<RUN_ID>/grounding.md\nrun_id: <RUN_ID>\ndensity_hint: <hint or 'unset'>\n\nYour entire final response will be saved verbatim by the orchestrator. Do not call the Write tool."
})

Issue all BREADTH Agent calls in a SINGLE message. This is the parallel fan-out — sequential dispatch defeats the purpose.

After all return, for each scout's response text:

Write({
  file_path: "reports/.work/<RUN_ID>/findings_L1_<angle_slug>.md",
  content: <verbatim scout response text>
})

DISPATCH_COUNT += BREADTH.

Verify each file has the expected frontmatter and at least 3 cited claims:

for f in reports/.work/<RUN_ID>/findings_L1_*.md; do
  if [ -e "$f" ]; then
    cov=$(grep -m1 "^coverage_score:" "$f" | sed 's/.*: //')
    claims=$(grep -c "^  - source:" "$f" 2>/dev/null || echo 0)
    echo "$f: coverage=$cov claims=$claims"
  fi
done

If any scout returned <3 claims OR no coverage_score frontmatter, re-dispatch that one scout with a sharpened angle phrasing (one retry; if still short, log to scratch and continue).

Step 3 — Loop: Reflect, then drill or synthesize

Set CURRENT_DEPTH=1.

While CURRENT_DEPTH < DEPTH AND DISPATCH_COUNT < MAX_DISPATCHES:

Step 3a — Dispatch reflector (Opus)

Agent({
  subagent_type: "general-purpose",
  description: "Reflect: gap detection",
  model: "opus",
  prompt: <contents of .claude/skills/research/prompts/reflector.md> + "\n\nInputs:\nrun_id: <RUN_ID>\ncurrent_depth: <CURRENT_DEPTH>\nmax_depth: <DEPTH>\ndispatch_count: <DISPATCH_COUNT>\nmax_dispatches: <MAX_DISPATCHES>\nbreadth: <BREADTH>\nthreshold: 0.70"
})

DISPATCH_COUNT += 1.

Read reports/.work/<RUN_ID>/reflection_L<CURRENT_DEPTH>.md. Parse the **Decision:** line.

If decision == "synthesize", break out of the loop.

Step 3b — Dispatch drill workers (if decision == drill)

Read the ## Drill questions JSON block from reflection_L<CURRENT_DEPTH>.md. For each drill question (up to BREADTH of them), dispatch one worker:

Agent({
  subagent_type: "general-purpose",
  model: "sonnet",
  description: "Drill: <slug>",
  prompt: <contents of .claude/skills/research/prompts/scout.md> + "\n\nInputs:\ntopic: <verbatim topic>\nangle: <drill question text>\nangle_slug: <drill slug>\ngrounding_brief_path: reports/.work/<RUN_ID>/grounding.md\nrun_id: <RUN_ID>\ndensity_hint: <inherit from parent angle, or 'narrative' if contrarian>\n\nThis is a drill (deeper layer follow-up) — tool budget is tighter: 2 WebSearch, 5 WebFetch, 2 Playwright. Stay tightly focused on the drill question. Your final response is your findings document; do not call Write."
})

Issue all drill dispatches in a SINGLE parallel message. After all return, persist each:

Write({
  file_path: "reports/.work/<RUN_ID>/findings_L<CURRENT_DEPTH + 1>_<drill_slug>.md",
  content: <verbatim drill response text>
})

DISPATCH_COUNT += <number of drills>. CURRENT_DEPTH += 1.

Loop back to Step 3a.

Step 4 — Synthesizer (Opus)

Agent({
  subagent_type: "general-purpose",
  description: "Synthesize: compose final report",
  model: "opus",
  prompt: <contents of .claude/skills/research/prompts/synthesizer.md> + "\n\nInputs:\nrun_id: <RUN_ID>\nmode: <MODE>\ndispatch_count: <DISPATCH_COUNT>\nbudget_capped: <true if loop ended via DISPATCH_COUNT >= MAX_DISPATCHES else false>"
})

DISPATCH_COUNT += 1.

Wait for completion. Verify reports/<RUN_ID>.md exists and contains the required sections per mode:

required=("TL;DR" "Findings")
if [ "$MODE" != "lite" ]; then
  required+=("Background" "Cross-angle synthesis" "Confidence map" "Open questions")
fi
for section in "${required[@]}"; do
  grep -q "^## $section" "reports/$RUN_ID.md" || echo "MISSING SECTION: $section"
done

Step 5 — Hand-off

Print to the user (terse — they read the report):

Run complete: <MODE>
Report: reports/<RUN_ID>.md
Dispatches: <DISPATCH_COUNT> / <MAX_DISPATCHES> | Depth reached: <CURRENT_DEPTH> | Budget capped: <yes/no>

Failure-mode notes

• Planner returns wrong angle count: stop and ask user. Don't fan out N≠BREADTH scouts.
• Scout returns <3 claims: retry once with a sharpened angle. If still short, log and continue — reflector handles the gap.
• Reflector says drill but BREADTH budget is exhausted: cap drill workers at MAX_DISPATCHES - DISPATCH_COUNT - 1 (reserve 1 for synth). If 0 remaining, force decision = synthesize, budget_capped = true.
• Synth fails to produce required sections: print the missing section list and stop. The report file may be partial; do not retry synth.
• Worker errors during fan-out: collect what returned successfully; don't fail the whole layer if 1 of 4 errors. Log the missing slug in scratch notes; reflector will treat it as low coverage.