deep-research

Deep Research - Orchestration Command

Parameters

Extract these parameters from the user's input:

Parameter	Required	Default	Description
RESEARCH_TOPIC	Yes	-	The user's research topic or questions (freeform text)

Environment values (resolve via shell):

• RP1_ROOT: !rp1 agent-tools rp1-root-dir (extract data.root from JSON response)

You are executing the Deep Research workflow. You coordinate autonomous research through a map-reduce architecture: clarify intent, spawn parallel explorers, synthesize findings, and delegate report generation.

CRITICAL: Commands CAN spawn agents. You will spawn research-explorer agents for exploration and research-reporter for report generation. Do NOT delegate orchestration to another agent.

STATE-MACHINE

stateDiagram-v2
    [*] --> clarify
    clarify --> plan : intent_clear
    plan --> explore : plan_ready
    explore --> synthesize : exploration_complete
    synthesize --> report : synthesis_complete
    report --> [*] : done

On each phase transition, report via:

rp1 agent-tools work update \
  --project "$(pwd)" \
  --feature {FEATURE_ID} \
  --workflow deep-research \
  --run-id {RUN_ID} \
  --step {CURRENT_STATE} \
  --status started

• Generate RUN_ID as a UUID at workflow start; derive FEATURE_ID by slugifying the research topic (e.g., "auth-flow-analysis")

State Progression Protocol:

1. Report each --step with --status started when you enter that state
2. For non-terminal states: move to the NEXT state when done (entering the next state implies the previous completed)
3. For terminal states (those with → [*] transitions): report --status completed when the step's work finishes
4. On error, transition to the appropriate failure state in the graph

Example sequence:

--step clarify --status started      # entering clarify phase
--step plan --status started         # intent clear, entering plan phase
--step explore --status started      # plan ready, entering explore phase
--step synthesize --status started   # exploration done, entering synthesize phase
--step report --status started       # synthesis done, entering report phase
--step report --status completed     # report work finished, workflow done

1. Intent Clarification (~15% effort)

Goal: Understand exactly what the user wants to research before spawning explorers.

Step 1: Parse Research Topic

Analyze the RESEARCH_TOPIC to identify:

• Primary question(s): What specific questions need answering?
• Research scope: Single project, multiple projects, or technical investigation?
• Target paths: Any project paths mentioned (defaults to current directory)
• Depth indicators: Is this a quick overview or deep dive?

Step 2: Determine if Clarification Needed

Use AskUserQuestion if RESEARCH_TOPIC is ambiguous about:

• Which codebase(s) to analyze
• Specific aspects to focus on (architecture, patterns, implementation, etc.)
• Expected output format or depth

Clear requests (skip clarification):

• "Understand the authentication flow in this project"
• "Compare error handling between ./project-a and ./project-b"
• "Research best practices for Redis caching"

Ambiguous requests (ask clarification):

• "Research this code" (which code? what aspects?)
• "Compare projects" (which projects?)
• "Help me understand" (understand what specifically?)

Step 3: Build Research Intent

After clarification (or immediately if clear), construct:

RESEARCH_INTENT:
- mode: single-project | multi-project | technical-investigation
- primary_questions: [list of specific questions to answer]
- target_projects: [list of project paths, or ["."] for current]
- focus_areas: [architecture | patterns | implementation | integration | performance]
- depth: overview | standard | deep

2. Exploration Planning (~5% effort)

Goal: Define explorer assignments for parallel execution.

Step 1: Determine Explorer Strategy

Based on RESEARCH_INTENT:

Single-project mode:

• Spawn 2-3 explorers per project with different focus areas
• Explorer 1: Architecture and structure (EXPLORATION_TYPE: codebase)
• Explorer 2: Implementation patterns (EXPLORATION_TYPE: codebase)
• Explorer 3: External context if needed (EXPLORATION_TYPE: web)

Multi-project mode:

• Spawn 1 explorer per project (each handles all aspects)
• Optional: Add 1 web explorer for cross-project context

Technical investigation mode:

• Spawn 1-2 codebase explorers for current project context
• Spawn 1-2 web explorers for external research

Step 2: Prepare Explorer Prompts

For each explorer, prepare:

• EXPLORATION_TARGET: Path or topic
• QUESTIONS: Subset of primary_questions relevant to this explorer
• EXPLORATION_TYPE: codebase | web | hybrid
• KB_PATH: Path to check for .rp1/context/ (for codebase explorers)

3. Spawn Explorers (~5% effort)

CRITICAL: Spawn ALL explorers in a SINGLE message with PARALLEL Task tool calls.

For each explorer:

{% dispatch_agent "rp1-base:research-explorer" %} Explore and return JSON findings. EXPLORATION_TARGET: {target} QUESTIONS: {stringify(questions)} EXPLORATION_TYPE: {type} KB_PATH: {kb_path}

Return structured JSON per output contract. {% enddispatch_agent %}

Naming convention: explorer-{n} where n is 1, 2, 3...

Wait for ALL explorers to complete before proceeding.

4. Collect and Synthesize Findings (~50% effort)

CRITICAL: Use extended thinking for this entire phase.

Step 1: Collect Explorer Results

Parse JSON output from each explorer:

• Validate JSON structure matches explorer output contract
• Extract findings arrays
• Extract questions_answered arrays
• Track explorer metadata (files explored, web searches, KB status)

Handle failures:

• If explorer returns invalid JSON: Log warning, skip that explorer
• If >50% explorers fail: Abort with error message to user
• Continue with partial results if <50% fail

Step 2: Merge Findings

Combine findings from all explorers:

• Deduplicate by finding content (similar titles/descriptions)
• Preserve all unique evidence
• Track which explorer(s) contributed each finding
• Assign merged finding IDs: F-001, F-002, etc.

Step 3: Synthesize Insights

Using extended thinking, analyze merged findings to:

1. Answer research questions: For each primary question, synthesize answer from supporting findings
2. Identify patterns: What patterns emerge across explorers/projects?
3. Note contradictions: Any conflicting findings between explorers?
4. Assess confidence: Overall confidence in findings (based on explorer confidence levels)

Step 4: Generate Recommendations

Based on synthesis, create actionable recommendations:

• Priority: high | medium | low
• Each recommendation ties to specific findings
• Include implementation notes where applicable

Step 5: Plan Diagrams

Identify diagrams that would aid understanding:

• Architecture diagrams for system structure findings
• Sequence diagrams for flow-related findings
• Comparison tables for multi-project analysis

For each diagram, specify:

• Type: flowchart | sequence | er | class
• Title: Brief descriptive title
• Description: What to visualize
• Elements: Key elements to include

Step 6: Build Synthesis Data Package

Construct the synthesis data JSON for the reporter:

{
  "topic": "<research topic>",
  "scope": "single-project | multi-project | technical-investigation",
  "projects_analyzed": ["<path1>", "<path2>"],
  "research_questions": ["<q1>", "<q2>"],
  "executive_summary": "<1-2 paragraph summary>",
  "findings": [
    {
      "id": "F-001",
      "category": "<category>",
      "title": "<title>",
      "description": "<description>",
      "confidence": "high | medium | low",
      "evidence": [...]
    }
  ],
  "comparative_analysis": {
    "aspects": ["<aspect1>", "<aspect2>"],
    "comparison_table": [
      {"aspect": "<aspect>", "project_a": "<approach>", "project_b": "<approach>", "analysis": "<comparison>"}
    ]
  },
  "recommendations": [
    {
      "id": "R-001",
      "action": "<action>",
      "priority": "high | medium | low",
      "rationale": "<why>",
      "implementation_notes": "<how>"
    }
  ],
  "diagram_specs": [
    {
      "id": "D-001",
      "title": "<title>",
      "type": "flowchart | sequence | er | class",
      "description": "<what to visualize>",
      "elements": ["<element descriptions>"]
    }
  ],
  "sources": {
    "codebase": ["<file:line> - <description>"],
    "external": ["<URL> - <description>"]
  },
  "metadata": {
    "explorers_spawned": "<count>",
    "kb_status": {"<project>": {"available": true, "files_loaded": ["..."]}},
    "files_explored": "<total_count>",
    "web_searches": "<total_count>"
  }
}

5. Spawn Reporter (~10% effort)

Step 1: Spawn Reporter Agent

The reporter handles output file naming (slugification, directory creation, deduplication).

{% dispatch_agent "rp1-base:research-reporter" %} Generate research report. SYNTHESIS_DATA: {stringify(synthesis_data)} RP1_ROOT: {{$RP1_ROOT}} REPORT_TYPE: {standard | comparative}

Return JSON with report status and path. {% enddispatch_agent %}

Step 2: Collect Reporter Result

Parse JSON output:

• Extract report_path
• Note diagrams_generated and diagrams_failed
• Track sections_written

Handle failure:

• If reporter fails: Log error, provide synthesis summary directly to user

Step 3: Register Artifact

After extracting report_path, register it in the artifact database:

rp1 agent-tools work artifact \
  --project "$(pwd)" \
  --feature {FEATURE_ID} \
  --run-id {RUN_ID} \
  --path {report_path}

6. Final Summary (~15% effort)

Output a concise summary to the user:

## Research Complete

**Topic**: {research_topic}
**Scope**: {scope}
**Projects Analyzed**: {project_list}

### Key Findings

{2-3 sentence summary of most important findings}

### Recommendations

- {Top recommendation 1}
- {Top recommendation 2}

### Report

Full report saved to: `{report_path}`

**Methodology**:
- Explorers spawned: {count}
- KB files loaded: {list or "none available"}
- Files explored: {count}
- Web searches: {count}
- Diagrams generated: {count}

Anti-Loop Directives

EXECUTE IMMEDIATELY:

• Do NOT ask for approval beyond initial clarification
• Do NOT iterate or refine after synthesis
• Do NOT re-run explorers
• Spawn explorers in PARALLEL (single message, multiple Task calls)
• Synthesis is ONE pass with extended thinking
• Output final summary after reporter completes
• STOP after outputting final summary

If blocked:

• Missing clarification: Ask ONE focused question, then proceed
• Explorer failures: Continue with available results if >50% succeed
• Reporter failure: Output synthesis summary directly
• Do NOT loop or retry failed components

Output Discipline

CRITICAL - Keep Output Focused:

• Use thinking for ALL internal planning and synthesis work
• Output to user:
  1. Brief acknowledgment of research topic
  2. Clarification question (if needed, max 1)
  3. Brief status when spawning explorers
  4. Final summary with report location
• Do NOT narrate each phase in detail
• Do NOT output raw JSON to user (only to subagents)

Error Handling

Error	Action
Ambiguous topic	Ask ONE clarifying question
No target projects	Default to current directory
Explorer JSON invalid	Skip explorer, continue if >50% succeed
>50% explorers fail	Abort with clear error message
Reporter fails	Output synthesis summary directly to user
No findings	Report "no significant findings" with methodology