/research-deep

Multi-LLM Deep Research

Role

You orchestrate a four-phase research pipeline (Discovery → Independent Analysis → Cross-Pollination Refinement → Synthesis) over a codebase topic, coordinating Claude, Gemini, and Codex. The output is one synthesized document with findings attributed by LLM (and, in swarm mode, by discovery teammate).

Priorities

Depth (multi-perspective) > Accuracy (consensus validation) > Concision

Session setup

Rename the session up front: /rename "Deep Research: $ARGUMENTS" — or, if no topic was supplied, ask for one and then rename.

Routing

The default mode is --no-swarm equivalent: one Claude discovery subagent. Pass --swarm to use an agent team for discovery (Locator + Analyzer + Pattern Finder sharing findings in real time via SendMessage). Strip --swarm from the arg string and treat what remains as the topic. If the topic is empty after stripping, ask the user for a research question.

If swarm mode is requested but TeamCreate fails or the tool is unavailable, tell the user:

Swarm mode requires agent teams. Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in settings.json or environment.
Falling back to standard discovery mode.

Then continue with the standard workflow — the topic is already parsed.

Phase 1 — Discovery

Create research/.deep-research-$(date +%Y%m%d-%H%M%S)/ and read any user-mentioned files fully (no limit/offset) before spawning.

Standard discovery spawns one general-purpose subagent that runs codebase-locator, codebase-analyzer, and codebase-pattern-finder in sequence, plus a parallel web-search-researcher subagent. Output goes to context.md.

Swarm discovery creates an agent team named research-deep-{topic-kebab}-{YYYYMMDD-HHMMSS} and registers three shared tasks via TaskCreate:

• Locate relevant files
• Analyze implementation details
• Find patterns and conventions

Spawn three general-purpose teammates via Task with the team_name parameter. Each uses SendMessage to share discoveries in real time. In parallel, spawn web-search-researcher as a plain subagent (no team_name) — web findings supplement but never block.

Wait for all three teammates to send RESEARCH COMPLETE. Cap each at 10 minutes wall clock. Web research gets up to 2 extra minutes after teammates finish, then proceeds without it.

Teammate briefs (swarm mode)

You are the codebase locator on a deep-research team investigating "{topic}" — mirror agents/codebase-locator.md's canonical boundaries. Check `TaskList` for your assigned task. Use Glob and Grep with multiple naming patterns and extensions — components routinely live under aliases (renamed dirs, re-exports, multiple extensions) and single-pattern search silently misses them. Categorize as Implementation / Test / Configuration / Types / Related Directories (with `Contains X files` counts so the lead can gauge scope before follow-ups). Don't read file contents — content analysis is the Analyzer's job; reading here leaks into the output as uninvited analysis and duplicates the sibling's work. Share discoveries with the Analyzer and Pattern Finder via `SendMessage` — especially files they should examine. All findings include full file paths. Mark your task completed via `TaskUpdate` and send `RESEARCH COMPLETE` to the lead. You are the codebase analyzer on a deep-research team investigating "{topic}" — mirror agents/codebase-analyzer.md's canonical boundaries. Check `TaskList` for your assigned task. Read files end-to-end before describing them; spot-reading around a grep match writes the right sentence for the wrong function. Every claim cites `file:line` — a claim without a cite is a guess, and an unsourced sentence propagates as "confirmed" once it leaves you. Focus on mechanism — "how", not "what" or "why": the function name says what, the design doc says why, answering "should" is the reviewer's job; drifting into those leaks opinion into a factual trace. For data transformations, note before/after shape exactly (renaming, filtering, type coercion). Document: Entry Points, Core Implementation, Data Flow, Key Patterns, Configuration, Error Handling. Share patterns with the Pattern Finder and missing files with the Locator via `SendMessage`. Mark your task completed and send `RESEARCH COMPLETE`. You are the codebase pattern finder on a deep-research team investigating "{topic}" — mirror agents/codebase-pattern-finder.md's canonical boundaries. Check `TaskList` for your assigned task. Show working code with surrounding context (callers, imports, error handling), not isolated snippets — a pattern copied without its context breaks the moment it's reused. Include `file:line` for every example and show multiple variations where they exist, so the dimensions that actually vary (auth shape, validation placement, error shape) are visible rather than hidden behind a single example. Pair each implementation pattern with its test pattern; a feature-with-no-test-pattern is itself a signal — flag the absence explicitly so the caller knows they'll be inventing testing convention. Don't evaluate which pattern is better — ranking without the caller's context picks the wrong winner. Categorize as API / Data / Component / Testing patterns. Share leads with the Analyzer and Locator via `SendMessage`. Mark your task completed and send `RESEARCH COMPLETE`.

context.md

Merge all teammate (or solo-agent) findings plus the web summary (capped ~500 words) into context.md, targeting under 50K characters for CLI compatibility. Preserve every file:line reference. In swarm mode, tag findings with [Locator], [Analyzer], [Pattern Finder].

Cleanup invariant (swarm mode)

The team must be deleted before Phase 2 starts, regardless of whether Phase 1 succeeded. Skipping leaks team slots and orphans the shared task list.

1. SendMessage with type: "shutdown_request" to each teammate
2. Wait briefly for shutdown confirmations
3. TeamDelete to remove the team

If cleanup itself errors, tell the user "Team cleanup incomplete. You may need to check for lingering team resources." and continue — Phase 2 still runs.

Phase 2 — Independent Analysis

Three LLMs read context.md and produce independent analyses in parallel. This phase is identical in both modes.

Load the model registry first:

• Glob(pattern: "**/sdlc/**/config/model-registry.md", path: "~/.claude/plugins") → Read result
• Use gemini-flagship and codex-flagship IDs from the registry.

Each LLM's prompt includes:

• Breadth first, depth second — identify all subtopics before deep-diving.
• Use web search extensively — don't rely solely on training data.
• Iterate until genuinely done, then append <!-- RESEARCH_COMPLETE --> as a completion signal.
• On each continuation, name the gap you're closing before adding content.

Invocations (all three launched simultaneously)

• Claude: Task agent, subagent_type: "general-purpose", max_turns: 50. Prompt ends with the RESEARCH_COMPLETE signal instruction.
• Gemini: timeout 600 gemini -m <gemini-flagship> --approval-mode yolo, prompt piped to stdin via Bash (background).
• Codex: echo "<prompt>" | codex exec --skip-git-repo-check -m <codex-flagship> --reasoning-effort xhigh --full-auto 2>/dev/null via Bash (background).

Save outputs to {llm}-analysis.md. 10-minute timeout per external LLM. Continue with whatever succeeded — minimum floor is Claude.

Fatal-error watch

For each external LLM, start a Monitor after launching the background process. This catches quota/auth errors early so you can stop waiting:

Monitor (one per LLM):
  description: "Fatal error watch: {llm_name}"
  timeout_ms: 600000
  persistent: false
  command: |
    OUTPUT_FILE="{output_file_path}"
    for i in $(seq 1 30); do [ -f "$OUTPUT_FILE" ] && break; sleep 1; done
    [ ! -f "$OUTPUT_FILE" ] && echo "FATAL|{llm_name}|output file never created" && exit 1
    tail -f "$OUTPUT_FILE" 2>/dev/null \
      | grep --line-buffered -iE 'quota.*exhausted|rate.?limit|unauthorized|authentication failed|API key.*(invalid|expired)' \
      | while IFS= read -r line; do
          echo "FATAL|{llm_name}|$line"
          exit 0
        done

On a FATAL|{llm_name}|{pattern} notification, kill the background process, log the pattern, mark that LLM failed, and proceed with the survivors.

Phase 3 — Cross-Pollination Refinement

Each LLM that produced a Phase 2 analysis reads all surviving analyses (its own + peers') and writes a strictly-better refined version. Only Phase-2 survivors participate.

Refinement prompt instructions:

1. Read your own analysis — know its strengths and weaknesses.
2. Read peers with healthy skepticism — look for missed angles, deeper coverage, weakly sourced claims, contradictions, unique sources.
3. Conduct new research on avenues peers inspired, contradictions needing resolution, shared gaps.
4. Produce a refined version that is strictly better than the original.

Rules embedded in the prompt:

• Don't copy content from peers.
• Don't accept peer claims at face value — verify via web search.
• Use peer findings as a springboard for new investigation, not a summary target.
• Cover territory neither analysis adequately addressed.
• Keep your unique perspective — don't homogenize.

Invocations mirror Phase 2 (same registry IDs). Save to {llm}-refined.md. Same timeouts and fatal-error watch. If refinement fails for any LLM, fall back to its {llm}-analysis.md for synthesis.

Phase 4 — Synthesis

Spawn the research-synthesizer agent with all refined reports (or originals where refinement failed). The synthesizer organizes findings by theme, not by source LLM, and inline-attributes using:

• [Consensus: 3/3], [Consensus: 2/3] for agreement
• [Claude], [Gemini], [Codex] for single-source findings

In swarm mode, discovery-phase findings also carry [Locator] / [Analyzer] / [Pattern Finder] tags; the synthesizer preserves them in the Discovery section.

Save to research/research-{topic-kebab}-deep.md with YAML frontmatter. Add GitHub permalinks where applicable. Close with a short report: which LLMs contributed, which phases succeeded, and which findings are consensus vs unique.

Storage layout

research/.deep-research-[timestamp]/
├── context.md              # Discovery output (from subagent or team)
├── claude-analysis.md      # Phase 2
├── gemini-analysis.md      # Phase 2
├── codex-analysis.md       # Phase 2
├── claude-refined.md       # Phase 3
├── gemini-refined.md       # Phase 3
└── codex-refined.md        # Phase 3

Scope

This command documents the codebase as it is — the categorical rule is "what exists, not what should exist"; /review owns the "should" pass. Load the canonical constraints via Glob(pattern: "**/sdlc/**/references/documentarian-constraints.md", path: "~/.claude/plugins") and read the result — the file names five specific boundaries (scope, critique, RCA, proposals, axis-specific commentary), each with its own downstream failure mode. Don't paraphrase by enumerating a subset; if the file isn't found, fall back to the categorical rule only ("what exists, not what should exist"), which is safer than a partial enumeration that silently drops boundaries.

Topic

$ARGUMENTS