Research

/research — Focused Investigation

When to Use

• Evaluating whether a dependency has a newer version or has been superseded
• Finding community best practices for a specific technical problem
• Reading official documentation for an API or library
• Investigating how other projects solve a similar problem
• Checking if a pattern used in the codebase has known issues
• Any time you need external information before making a decision

Don't use when: you need to act on findings immediately (use /marshal which calls /research internally).

Modes

Single (default): one agent, 2-4 queries, 3-6 sources. Steps 1-5 below.

Parallel (/research --parallel): scout agents investigate independent angles of the same question using Fleet wave mechanics. See Parallel Mode below. Without the flag, prefer parallel mode (and say so in the plan) when the question naturally decomposes into 3+ independent angles: evaluating multiple competing technologies or approaches, distinct sub-questions that don't depend on each other, or time-sensitive research where parallel execution matters.

If the question is narrow and focused, stay single-agent. Don't parallelize what a single agent can answer in 5 minutes.

Protocol (Single Mode)

Step 1: FORMULATE

Convert the research question into 2-4 specific search queries:

• Official docs query (e.g., "express.js middleware error handling docs")
• Community/GitHub query (e.g., "express error middleware best practices site:github.com")
• Technical blog/comparison query (e.g., "express vs fastify error handling 2025")
• Release notes query if version-specific (e.g., "express 5.x changelog breaking changes")

State the question clearly in one sentence before searching.

Step 2: SEARCH

Execute searches and read actual content (not just snippets):

• Use WebSearch for discovery, WebFetch for reading actual pages
• Evaluate source credibility: official docs > GitHub repos with stars > recent blog posts > forum answers
• Stop at 3-6 credible sources (not exhaustive — focused)
• If a source contradicts another, note the disagreement

The WebFetch Restrictions under Parallel Mode apply in single mode too: never WebFetch rendered GitHub pages.

Step 3: EXTRACT

For each finding, record:

• What: The specific fact, recommendation, or pattern discovered
• Source: URL or reference
• Relevance: How this applies to the original question (one sentence)
• Confidence: high (official docs, verified), medium (community consensus), low (single source, opinion)
• Action: What the codebase should do with this information (or "informational only")

Step 4: WRITE

Write findings to .planning/research/{topic-slug}.md:

# Research: {Topic}

> Question: {The original question}
> Date: {ISO date}
> Confidence: {overall: high/medium/low}

## Findings

### 1. {Finding title}
**What:** {description}
**Source:** {URL}
**Confidence:** {high/medium/low}
**Action:** {recommendation or "informational"}

### 2. {Finding title}
...

## Summary
{2-3 sentences: what was learned, what the recommendation is}

## Open Questions
{Anything that couldn't be resolved — needs human judgment or deeper investigation}

Step 5: RETURN

Return the summary and recommendation to the caller (user, Marshal, or Archon). The research document persists for future reference.

Parallel Mode (--parallel)

The former /research-fleet behavior now lives in this parallel mode. Spawns multiple scout agents, each investigating a different angle of the same question. Findings are compressed between waves. Produces a unified research brief from multiple independent perspectives.

Inputs: the question, plus optional angles (specific sub-questions to investigate). If not provided, decompose the question into 3-5 angles automatically.

Step P1: 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 P1b: INITIALIZE GRAPH (Explicit Opt-In)

With explicit --operation-graph, assign 3-5 opaque angle IDs and initialize a graph plus bound operation: node .citadel/scripts/operation-graph-runner.js research-init --project-root . --graph .planning/research/fleet-{slug}/operation-graph.json --operation .planning/research/fleet-{slug}/operation-spec.json --journal .planning/research/fleet-{slug}/graph-journal --run-id research-{slug} --angles {id1,id2,id3} For each P2-P5 node, call node .citadel/scripts/operation-graph-effects.js start with the graph journal, --effects .../effect-journal, node ID, and payload digest before work; call node .citadel/scripts/operation-graph-effects.js complete with its evidence digest after verification. Keep prompts and findings outside graph state. On resume run node .citadel/scripts/operation-graph-effects.js status; resolve blocked nonrepeatable work with reviewed evidence. After the arbiter passes, run node .citadel/scripts/operation-graph-effects.js receipt with the bound operation. Without the flag, create no graph state.

Step P2: 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 single-mode protocol (formulate, search, extract, write)
4. Each scout writes its findings to .planning/research/fleet-{slug}/{angle-slug}.md

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

Step P3: 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 P4: 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 P5: REPORT

Write the unified report to .planning/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}

Log the completed wave through Citadel's project-local telemetry helper:

node .citadel/scripts/telemetry-log.cjs --event wave-complete --agent research-fleet --session fleet-{slug} --status success

If the helper is unavailable, skip telemetry without blocking the research result. Keep the scout count and total wave count authoritative in REPORT.md and the parallel-mode HANDOFF rather than duplicating them in telemetry metadata.