deep-research

What this skill does

# Deep Research

Conduct thorough, multi-source research on a topic with iterative investigation, cross-verification, and structured synthesis into a cited report.

## Overview

Deep research goes beyond a single search query. It decomposes a question into sub-topics, investigates each through multiple sources, identifies gaps, iterates to fill them, and synthesizes findings into a structured report with citations. The process is designed for transparency — the user sees the plan, approves it, and can steer the investigation.

## Task Tracking

Use `TaskCreate` and `TaskUpdate` throughout the research process to give the user visibility into progress. This is mandatory — do not skip task creation.

1. **At the start of Phase 2**, create a task for each sub-question from the research plan (e.g., "Investigate: [sub-question]"). Use `activeForm` to show what's happening in the spinner (e.g., "Investigating [sub-question]").
2. **At the start of each subsequent phase** (Draft, Adversarial Review, Editorial Synthesis, Deliver), create a task for that phase.
3. **Mark tasks `in_progress`** when you begin working on them and `completed` when done.
4. **For sub-agents**, create their tasks before launching them so the user can see parallel work in progress.

Keep task subjects short and specific. The description field should include enough context to understand scope.

## Effort Levels

Research intensity is controlled by an effort parameter: **low**, **medium** (default), **high**, or **ultra**. This acts as an exponential multiplier across the entire process.

| Parameter              | Low                                  | Medium         | High                       | Ultra                                           |
| ---------------------- | ------------------------------------ | -------------- | -------------------------- | ----------------------------------------------- |
| Sub-questions          | 3-5                                  | 5-7            | 8-12                       | 15-20                                           |
| Parallel agents        | 2                                    | 3-4            | 6-8                        | 10+                                             |
| Sources per question   | ~4                                   | ~8             | ~15                        | ~25+                                            |
| Iteration rounds (max) | 2                                    | 3              | 4                          | 6                                               |
| Adversarial review     | Lightweight (no source verification) | Full           | Full + source verification | Full + multiple reviewers + source verification |
| Output format          | Markdown + PDF                       | Markdown + PDF | Markdown + PDF             | Markdown + PDF (detailed)                       |
| Report length          | 3-5 pages                            | 6-12 pages     | 15-25 pages                | 30+ pages                                       |

**Determining effort:**

- "quick research", "brief overview" → **low**
- No qualifier (default) → **medium**
- "thorough", "comprehensive", "deep dive" → **high**
- "exhaustive", "leave no stone unturned", explicit "ultra" → **ultra**
- User can also specify explicitly (e.g., `/deep-research high: topic`)

All parameters in the workflow below (sub-question count, agent count, iteration limits, etc.) must follow the effort level table. When launching sub-agents, pass the effort level so they calibrate their depth accordingly.

## Core Workflow

Execute these phases in order. Do not skip Phase 1 or Phase 2.

### Phase 1: Plan (Interactive)

Before any searching, decompose the user's question:

1. **Clarify scope** — If the query is ambiguous, ask 1-2 focused questions (not more) to narrow down what the user actually needs. Skip if the intent is already clear.
2. **Decompose into sub-questions** — Break the topic into sub-questions per the effort level table. Each should target a distinct angle (e.g., "how does X work?", "what are alternatives to X?", "what do practitioners say about X?").
3. **Identify source types** — For each sub-question, note where to look: official docs, GitHub repos, HN discussions, academic papers, blog posts, Wikipedia, etc.
4. **Present the plan** — Show the user the research plan as a numbered list of sub-questions with source strategies. Ask for approval or modifications before proceeding.

```markdown
## Research Plan: [Topic]

### Sub-questions

1. [Sub-question] — Sources: [where to look]
2. [Sub-question] — Sources: [where to look]
   ...

### Effort: [low/medium/high/ultra]

- Sub-questions: [N] (per effort table)
- Sources per question: ~[M]
- Parallel agents: [P]
- Max iterations: [I]

Proceed with this plan?
```

### Phase 2: Investigate (Iterative)

For each sub-question, execute this loop:

```
SEARCH → READ → EXTRACT → EVALUATE → (iterate if gaps remain)
```

**Search strategy:**

- Start with `WebSearch` for broad discovery
- Use lightpanda for full page content extraction per global instructions
- Fall back to `WebFetch` if lightpanda fails on a particular URL
- For detailed search strategies and source evaluation heuristics, read `references/research-patterns.md`
- Use `Agent` tool to parallelize independent sub-question investigations — launch multiple research sub-agents for unrelated sub-questions simultaneously
- For GitHub-specific research, use `gh search repos`, `gh search code`, and browse READMEs directly

**Source priorities** (per user preferences):

1. GitHub repositories and READMEs
2. Hacker News discussions and comments
3. Wikipedia
4. Official documentation and first-party sources
5. Technical blog posts and articles
6. Academic papers (when relevant)

**Per-source extraction:**

- Extract key claims, data points, and quotes
- Note the source URL and a brief credibility assessment
- Flag disagreements between sources explicitly

**Gap analysis after each round:**

- List what is now known vs. what remains unanswered
- If significant gaps remain, formulate new search queries targeting those gaps
- Limit iterations to the maximum specified by the effort level table — after reaching the limit, synthesize with what is available and note remaining unknowns

**Context management:**

- After extracting findings from a source, distill them into bullet points — do not carry full page content forward
- Use a running findings list organized by sub-question
- When context grows large, summarize completed sub-questions to free up space

### Phase 2.5: Cross-Agent Reconciliation

When multiple agents investigated overlapping sub-questions, reconcile before drafting:

1. **Identify contradictions** — Compare agent findings on the same topic. Flag any claims where agents disagree.
2. **Resolve or escalate** — For each contradiction:
   - If one agent cited a primary source and the other cited a secondary source, prefer the primary
   - If both have equal sourcing, do a targeted follow-up search to break the tie
   - If unresolvable, note explicitly as contested in the draft
3. **Merge findings** — Create a unified findings list organized by sub-question (not by agent) before proceeding to the draft

### Phase 3: Draft Report

Compile findings into a structured markdown draft report:

```markdown
# [Research Topic]

## Summary

[2-3 paragraph executive summary of key findings]

## Findings

### [Sub-topic 1]

[Synthesized findings with inline citations as numbered references, e.g. [1]]

### [Sub-topic 2]

...

## Key Takeaways

- [Actionable insight 1]
- [Actionable insight 2]
- ...

## Open Questions

- [What remains unknown or contested]

## Sources

1. [Title](URL) — [brief description]
2. [Title](URL) — [brief description]
   ...
```

**Synthesis principles:**

- Cross-verify claims that appear in multiple sources; note conflicts
- Distinguish between widely-agreed facts and individual opinions
- Lead with what matters most