Research Fleet

The user provides:

1. question: The research topic or question
2. angles (optional): Specific sub-questions to investigate. If not provided, the skill decomposes the question into 3-5 angles automatically.

Protocol

Step 1: DECOMPOSE

Break the research question into 3-5 independent angles:

Example: "Should we migrate from Express to Fastify?"

• Scout 1: Performance benchmarks (Express vs Fastify vs Hono, latest data)
• Scout 2: Migration effort (breaking changes, middleware compatibility, ecosystem)
• Scout 3: Community health (GitHub stars trend, npm downloads, maintainer activity)
• Scout 4: Production war stories (who migrated, what broke, was it worth it)

Each angle must be:

• Independent (scout doesn't need another scout's findings to do its work)
• Specific (one clear question per scout)
• Answerable (3-6 sources should be sufficient)

Step 2: DEPLOY WAVE 1

Spawn one scout agent per angle using Fleet wave mechanics:

For each scout:

1. Create an isolated worktree
2. Inject the scout's specific angle as the research question
3. Each scout follows the research skill protocol (formulate, search, extract, write)
4. Each scout writes its findings to .citadel/research/fleet-{slug}/{angle-slug}.md

All scouts run in parallel. Wait for all to complete.

Step 3: COMPRESS

After Wave 1 completes:

1. Read all scout findings
2. Identify:
   • Consensus: findings that multiple scouts independently confirmed
   • Conflicts: findings that contradict each other (flag these prominently)
   • Gaps: angles that didn't produce strong results (consider a Wave 2)
   • Surprises: unexpected findings that change the framing of the question
3. Compress into a unified brief (~500 tokens)

Step 4: WAVE 2 (Optional)

If gaps or conflicts exist:

1. Spawn targeted scouts to resolve specific conflicts or fill gaps
2. Each Wave 2 scout receives the compressed brief from Wave 1 as context
3. Wave 2 scouts don't re-research what Wave 1 already covered

Skip Wave 2 if Wave 1 produced clear, consistent findings.

Step 5: REPORT

Write the unified report to .citadel/research/fleet-{slug}/REPORT.md:

# Research Fleet: {Topic}

> Question: {The original question}
> Date: {ISO date}
> Scouts: {N} across {waves} wave(s)
> Confidence: {overall: high/medium/low}

## Consensus Findings
{Findings confirmed by 2+ scouts}

## Conflicts
{Findings where scouts disagreed — present both sides}

## Key Findings by Angle

### {Angle 1}: {title}
{Summary from scout 1}
Source: {scout report path}

### {Angle 2}: {title}
{Summary from scout 2}
Source: {scout report path}

...

## Recommendation
{2-3 sentences: what the evidence says, what the recommendation is}

## Open Questions
{What couldn't be resolved — needs human judgment}

Also log to .citadel/telemetry/agent-runs.jsonl:

{"event":"research-fleet-complete","slug":"{slug}","scouts":0,"waves":0,"timestamp":"ISO"}

Safety Rules

• Maximum 5 scouts per wave (don't burn tokens on diminishing angles)
• Maximum 2 waves (if Wave 2 doesn't resolve it, the question needs human judgment)
• Each scout follows research skill quality gates (sources, confidence, evidence)
• Scout findings are independent. No scout reads another scout's output during the same wave.
• Scout timeout: 15 minutes (configurable via harness.json agentTimeouts.research). If a scout exceeds its timeout, skip it and proceed with other scouts' results. A timed-out scout's angle becomes a "Gap" in the final report.

WebFetch Restrictions

Every scout prompt MUST include this instruction:

Do NOT use WebFetch on GitHub repository pages (github.com/{user}/{repo}). These pages are massive HTML documents (500KB+) that hang the fetcher indefinitely. Instead:

• Use WebSearch to find information about repos (search snippets contain what you need)
• If you need a repo's README content, fetch the raw URL: https://raw.githubusercontent.com/{user}/{repo}/{branch}/README.md
• Never fetch rendered GitHub pages: issues, pull requests, repo root, or file views

This restriction exists because a real research-fleet run hung for 38+ minutes on WebFetch(https://github.com/jehna/readme-best-practices) with zero output. The circuit breaker didn't catch it because the tool didn't fail — it just never completed.

Quality Gates

• Every scout must produce a findings document
• Conflicts must be explicitly flagged, not silently resolved
• The compressed brief must be written before spawning Wave 2
• The final report must answer the original question or state why it can't

Exit Protocol

---HANDOFF---
- Research Fleet: {topic}
- Scouts: {N} across {waves} wave(s)
- Consensus: {one-line summary of agreed findings}
- Conflicts: {any unresolved disagreements}
- Recommendation: {one-line}
- Report: .citadel/research/fleet-{slug}/REPORT.md
---