Deep Research Pipeline

Host-side only (Claude Code). See docs/agent-agnostic-debt.md AAG-012 for backend parity status.

A 4-stage research pipeline. Classifies research depth, clarifies scope when ambiguous, then routes to shallow or deep retrieval with structured citation-backed output.

Design pattern: Mediator. This skill is the central coordinator. Research scouts and brainstormer are independent peers invoked through the Agent tool without cross-coupling. Neither agent knows about the other or about the pipeline stages.

Composes existing infrastructure — does NOT duplicate it:

• Research scout agents for evidence-classified source finding (deep path)
• brainstormer agent for creative synthesis (when the user wants ideas, not just facts)
• Parallel AI MCP for web search when available (graceful fallback to WebSearch)
• Vault memory for prior decisions and research
• NotebookLM for querying existing notebooks when relevant

Instructions

When the user invokes /deep-research <topic> or a trigger phrase matches:

Stage 1: Classify intent

Read the query and classify into one of:

Depth	Signal	Example
SHALLOW	Single fact, narrow scope, recent event, quick comparison	"What's the latest on X?", "Compare A vs B briefly"
DEEP	Multi-source synthesis, historical overview, regulatory landscape, decision brief, "research X"	"Research the regulatory landscape for Y", "Produce a brief on Z"
CREATIVE	Solution design, brainstorming, "how could we", exploration of alternatives	"How could we improve X?", "What are creative approaches to Y?"

State the classification and proceed. Do NOT ask the user to confirm depth — only ask if the topic itself is ambiguous (Stage 2).

Stage 2: Clarify scope (conditional)

Skip this stage if the query is specific enough to research directly. Most queries are.

Only use AskUserQuestion when genuinely ambiguous — when researching the wrong scope would waste significant effort:

AskUserQuestion:
  question: "Your query could mean several things. Which scope should I research?"
  options:
    - { label: "<interpretation 1>", description: "<what this covers>" }
    - { label: "<interpretation 2>", description: "<what this covers>" }
    - { label: "Both", description: "Research both angles" }

Also clarify if the user hasn't indicated:

• Time horizon — for queries where recency matters ("last 6 months" vs "all time")
• Output format — only if unclear (default: structured report with citations)

Stage 3: Retrieve (route by depth)

---

SHALLOW path

Single-pass retrieval. No subagents. Target: 30-60 seconds.

1. Vault memory — check for prior work:

   python3 ~/deus/scripts/memory_tree.py query "<topic keywords>" 2>/dev/null
   

   Read top 2-3 results if confidence > 0.4.

2. Web search — run 2-3 queries with different phrasings:

   • If Parallel AI is available: prefer mcp__parallel-search__search (faster, structured results)
   • If that tool is not registered (tool-not-found error): fall back to WebSearch
   • Use WebFetch to read the top 2-3 most relevant results in full

3. Synthesize inline — produce a concise answer with source citations. Go directly to Stage 4 output format (abbreviated — no evidence taxonomy needed for shallow).

---

DEEP path

Parallel fan-out via subagents. Target: 2-5 minutes.

Step 1: Parallel retrieval — launch in a single message

Launch these retrieval tasks in parallel using the Agent tool:

A. Research scout (primary domain):

Agent(subagent_type="general-purpose", model="sonnet"):
  You are a research scout. Find and classify sources with evidence-quality ratings.
  You cast a wide net but NEVER synthesize — list and classify only.

  Research topic: <primary domain framing of the query>
  Focus: primary domain sources — papers, benchmarks, implementations, authoritative references.

  Procedure:
  1. Run 2-3 WebSearch queries with different phrasings
  2. Read top results with WebFetch
  3. Search GitHub (via WebSearch) for relevant implementations
  4. Classify every source using this taxonomy:
     - empirical: peer-reviewed or reproducible experiment
     - benchmark: quantitative comparison on a standard dataset
     - implementation: working code that demonstrates the approach
     - anecdotal: first-person experience without controlled methodology
     - vendor: claims from the entity selling the tool
     - theoretical: formal analysis without empirical validation

  Output for each source (mandatory schema):
  ### <source number>. <source title>
  - **URL**: <url>
  - **Evidence quality**: <label from taxonomy>
  - **Date**: <publication date>
  - **Core claim**: <one sentence>
  - **Relevance**: <why this matters for the research question>
  - **Limitations**: <what this source doesn't cover>

  Minimum 5 sources. Never fabricate URLs. Include a source count by evidence quality at the end.

B. Research scout (adjacent domain):

Agent(subagent_type="general-purpose", model="sonnet"):
  You are a research scout. Find and classify sources with evidence-quality ratings.
  You cast a wide net but NEVER synthesize — list and classify only.

  Research topic: <adjacent domain framing — a related field with transferable insights>
  Focus: cross-pollination from <adjacent field>. Look for techniques, patterns, or solutions
  from this domain that could transfer to the primary question.

  Procedure:
  1. Run 1-2 WebSearch queries in the adjacent domain
  2. Read top results with WebFetch
  3. Search GitHub (via WebSearch) for relevant implementations
  4. Classify every source using the evidence taxonomy:
     empirical | benchmark | implementation | anecdotal | vendor | theoretical

  Output for each source (mandatory schema):
  ### <source number>. <source title>
  - **URL**: <url>
  - **Evidence quality**: <label from taxonomy>
  - **Date**: <publication date>
  - **Core claim**: <one sentence>
  - **Relevance**: <why this matters for the research question>
  - **Limitations**: <what this source doesn't cover>

  Document what was searched even if nothing relevant was found. Include coverage gaps.

C. Vault + internal context:

python3 ~/deus/scripts/memory_tree.py query "<topic keywords>" 2>/dev/null

Read top results. Also check ~/deus/docs/decisions/INDEX.md for relevant ADRs.

D. Parallel AI deep research (optional — only when available AND topic warrants it):

If Parallel AI MCP is available (tool resolves without error) and the topic is complex enough to justify async research:

AskUserQuestion:
  question: "I can also run Parallel AI deep research on this topic (2-5 min, higher cost). Include it?"
  options:
    - { label: "Yes", description: "Adds a comprehensive AI-generated analysis to the source pool" }
    - { label: "No, existing sources are enough", description: "Proceed with web research results only" }

If yes: call mcp__parallel-task__create_task_run and poll for results. Include the Parallel AI output as one source in the synthesis (with vendor evidence quality label since it's AI-generated).

E. NotebookLM (optional — only when the user has notebooks related to the topic):

If the topic overlaps with known NotebookLM notebooks:

mcp__notebooklm-mcp__notebook_query: query the most relevant notebook

Include results as internal source material.

Step 2: Wait for all parallel tasks to complete.

Collect all findings. You should now have:

• Primary domain findings (5+ classified sources)
• Adjacent domain findings (additional sources)
• Vault memory hits (prior decisions, research notes)
• Optionally: Parallel AI analysis, NotebookLM results

Step 3: Synthesize.

This is where you add value beyond what the research scouts provide. Scouts find and classify — you synthesize, connect, and conclude.

Synthesis rules:

• Every factual claim must cite a specific source from the findings
• When sources disagree, present both positions with their evidence quality labels
• Highlight cross-domain connections (insights from adjacent domain that apply to primary)
• Flag coverage gaps — what the research couldn't find
• Distinguish between what's well-established (multiple empirical/benchmark sources) and what's speculative (single anecdotal/vendor source)

---

CREATIVE path

Route to brainstormer with the research context.

1. Run the SHALLOW retrieval first (vault + web search) to gather context.
2. Launch brainstormer with the enriched prompt:

   Agent(subagent_type="brainstormer"):
     Problem statement: <user's query>
     Pre-gathered context: <vault memory hits and web search findings>
     Generate 3-5 ranked solution ideas with effort/impact/risk.
   

3. Present brainstormer output directly — it already has a structured format.

---

Stage 4: Output

Shallow output format

# Research: <topic>

<2-4 paragraph synthesis answering the query>

## Sources
1. [<title>](<url>) — <one-line summary>
2. ...

## Vault Context
- <relevant prior decisions or research, if any>

Deep output format

# Research Report: <topic>

**Date:** YYYY-MM-DD
**Depth:** Deep | Research time: ~Xm
**Sources reviewed:** N (M empirical, N benchmark, O implementation, P anecdotal, Q vendor)

## Executive Summary

<3-5 sentences capturing the key findings and their confidence level>

## Findings

### <Theme/Section 1>

<Synthesis paragraph with inline citations [1][2]>

### <Theme/Section 2>

<Synthesis paragraph with inline citations [3][4]>

### Cross-Domain Insights

<Connections from adjacent domain research that apply here>

## Evidence Map

| # | Source | Evidence Quality | Core Claim |
|---|--------|-----------------|------------|
| 1 | [<title>](<url>) | empirical | <one sentence> |
| 2 | [<title>](<url>) | benchmark | <one sentence> |
| ... | ... | ... | ... |

## Confidence Assessment

- **High confidence:** <claims backed by multiple empirical/benchmark sources>
- **Medium confidence:** <claims with implementation evidence but limited empirical>
- **Low confidence / Speculative:** <claims from single anecdotal/vendor sources>

## Coverage Gaps

- <what was searched for but not found>
- <domains that might have relevant work but weren't explored>

## Prior Decisions (Vault)

- <relevant ADRs, research notes, or past decisions — with memory path citations>
- <or "No prior decisions found for this topic">

Creative output format

Use the brainstormer's native output format (ranked ideas with effort/impact/risk table).

Stage 5: Follow-up

After presenting results, offer next steps via AskUserQuestion:

AskUserQuestion:
  question: "Research complete. What would you like to do next?"
  options:
    - { label: "Save to vault", description: "Persist this research to Deus memory for future reference" }
    - { label: "Go deeper on a section", description: "Run targeted deep research on a specific finding" }
    - { label: "Done", description: "No further action needed" }

If "Save to vault": Use the preserve skill to save the research report as a durable memory artifact.

If "Go deeper": Ask which section, then re-run the DEEP path scoped to that subtopic.

Constraints

• NEVER fabricate URLs or citations. Every source must come from actual retrieval results.
• NEVER present AI-generated content (from Parallel AI or your own synthesis) as primary evidence — always label it.
• NEVER skip the evidence quality classification on deep path. Every source gets a label.
• NEVER run the deep path for queries that are clearly shallow — respect the user's time.
• If vault memory has a relevant prior decision that contradicts web sources, flag the conflict explicitly rather than silently favoring either.
• Minimum 5 sources for deep path reports. If fewer found, document what was searched.
• Adjacent domain search is mandatory on deep path, even if it yields nothing — document the attempt.