research-fleet

Files (1)

• SKILL.md

SKILL.md (first lines)

# research-fleet — Parallel Multi-Scout Research

## Identity

research-fleet is the research skill scaled to parallel execution. Instead of one agent
running 2-4 queries sequentially, multiple scout agents investigate different
angles simultaneously. Each scout produces independent findings. Between waves,
findings are compressed into a unified brief.

Use this when the question is broad enough that multiple perspectives would
produce better results than depth on a single thread.

## When to Use Over research skill

- Evaluating multiple competing technologies or approaches
- Researching a topic with distinct sub-questions that don't depend on each other
- Time-sensitive research where parallel execution matters
- Any research question that naturally decomposes into 3+ independent angles

If the question is narrow and focused, use the research skill instead. Don't
parallelize what a single agent can answer in 5 minutes.

## Inputs

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`:

```markdown
# 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`:
```json

From special-place-administrator/citadel_codex, MIT.

More from special-place-administrator/citadel_codex