# Deep Research Command

Conducts comprehensive research on complex topics with technical rigor, synthesizing multiple sources including academic papers, technical documentation, industry reports, and practitioner insights.

## Usage

```
/deep-research [topic]
```

## Purpose

Execute a systematic research workflow that:
- Clarifies research parameters through structured dialog
- Creates a detailed research plan
- Conducts parallel source investigation
- Synthesizes findings into comprehensive documentation
- Produces research-ready artifacts with proper citations

## Prerequisites

- Access to web search and fetch capabilities
- Sufficient time for thorough investigation (varies by depth)

## Workflow Steps

### Phase 0: Topic Identification

**If the user invoked the command without a topic** (e.g., just `/deep-research`):

Ask an open-ended question: "What topic or research question would you like to investigate?"

**If the user provided a topic** (e.g., `/deep-research distributed systems patterns`):

- Proceed directly to Phase 1 with the provided topic

### Phase 1: Initial Clarification

Use the **AskUserQuestion** tool to gather structured feedback on research parameters.

Ask the user to clarify:

1. **Research purpose**: What is the goal of this research/what angles should be explored? Suggest options contextually. (use AskUserQuestion with multiSelect: true)
2. **Scope boundaries**: What should be included/excluded? Any constraints? Suggest options contextually. (use AskUserQuestion with multiSelect: true)
3. **Source preferences**: Which types are most valuable? (use AskUserQuestion with multiSelect: true)
   - Academic papers and peer-reviewed research
   - Technical documentation / Industry whitepapers
   - Technical blogs from recognized experts
   - Practitioner discussions (Reddit, X, LinkedIn, HackerNews)
   - Company documentation and case studies
4. **Research depth**: How many sources? (use AskUserQuestion with options for Light: 6-8, Medium: 9-14, Deep: 15+)

### Phase 2: Planning & Approval

**Brief preliminary investigation:**

- Search for 2-3 representative sources
- Identify major themes, terminology, key authors/organizations
- Note unexpected angles or adjacent topics worth exploring

**Create research plan:**

1. Use template from `plugins/dot-claude/commands/templates/research-plan.md`
2. Ask the user where they would like you to save your work or if you should create a new working directory
3. Create `/[RESEARCH TOPIC]` inside the working directory
4. Create and save your research plan to `[YOUR WORKING DIRECTORY]/[RESEARCH TOPIC]/plan.md`

**Plan structure:**

- **Research angles**: 3-5 core sub-questions or perspectives
- **Source strategy**: Mix of source types with target quantities based on user preferences
- **Analysis approach**: Synthesis method (thematic, comparative, chronological)
- **Expected deliverables**: Final format and supporting documentation
- **Potential challenges**: Known gaps, access issues, complexity factors

---

### Phase 3: Research Execution & Synthesis

#### Overview

Research is conducted by spawning multiple researcher subagents simultaneously—one for each source topic. Each researcher independently fetches, analyzes, and creates a comprehensive summary of their assigned source. After all researchers complete, you synthesize their findings into a unified research document.

**Research approach:**
- All sources researched simultaneously for faster execution
- Research follows the initial research plan established in Phase 2
- Comprehensive individual summaries from each researcher
- Final synthesis integrates all findings after research is complete

#### Step 1: Setup

1. Create synthesis file from template: `plugins/dot-claude/commands/templates/research-synthesis.md`
2. Save to: `[YOUR WORKING DIRECTORY]/[RESEARCH TOPIC]/synthesis.md`
3. Create summaries directory: `[YOUR WORKING DIRECTORY]/[RESEARCH TOPIC]/summaries/`

#### Step 2: Identify Research Topics

From the approved research plan, identify specific search queries to research. Aim for target source count from Phase 1 (6-8 for Light, 9-14 for Medium, 15+ for Deep).

**For each research angle in the plan**, identify 2-4 specific search queries to investigate:

Example:

- Research Angle: "Performance patterns in distributed systems"
  - Query 1: "Kubernetes horizontal pod autoscaling best practices"
  - Query 2: "Netflix microservices scaling strategies"
  - Query 3: "Load balancing algorithms for distributed systems"

Create a list of N search queries to research (where N = target source count).

#### Step 3: Find and Validate URLs

**CRITICAL: You must identify and validate specific URLs before spawning any researcher subagents.**

For each search query from Step 2:

1. Use WebSearch to find relevant sources
2. Identify a specific URL from the search results that best addresses the query
3. Use WebFetch with a simple prompt (e.g., "Extract the title and first paragraph") to verify each URL is accessible
4. If a URL is not accessible, find an alternative URL for that query and validate it
5. Compile a list of N validated URLs (one per query)

**Do not proceed to Step 4 until you have N validated, accessible URLs.**

Document the validated URLs clearly, noting which research angle and query each URL addresses.

#### Step 4: Spawn Researcher Subagents in Parallel

**CRITICAL: Use a single message with multiple Task tool calls to execute all researchers in parallel.**

For each validated URL from Step 3, spawn a researcher subagent using the Task tool:

```
Task tool parameters for each researcher:
- subagent_type: "dot-claude-agents:research-analyst"
- description: "Research [brief topic description]"
- prompt: "You are executing the researcher subagent role defined in plugins/dot-claude/agents/research-analyst.md.

Your assignment:
- Source URL: [VALIDATED_URL]
- Research focus: [specific research angle from plan]
- Research purpose: [overall research goal from Phase 1]
- Working directory: [YOUR WORKING DIRECTORY]/[RESEARCH TOPIC]

Follow the instructions in plugins/dot-claude/agents/research-analyst.md to:
1. Fetch the source using WebFetch on the provided URL
2. Conduct deep analysis
3. Create comprehensive summary using plugins/dot-claude/skills/analyzing-source/templates/article-summary.md
4. Save to: [YOUR WORKING DIRECTORY]/[RESEARCH TOPIC]/summaries/[descriptive-filename].md

Provide a brief confirmation when complete with the key insights discovered."
```

**Execute all N researchers in parallel by including N Task tool calls in a single message.**

#### Step 5: Wait for Completion

All researcher subagents will execute in parallel. Wait for all to complete before proceeding.

#### Step 6: Review Researcher Outputs

Once all researchers have completed:

1. List all summary files created in `[YOUR WORKING DIRECTORY]/[RESEARCH TOPIC]/summaries/`
2. Read each source summary file to understand what each researcher discovered
3. Note the range of perspectives, key themes, contradictions, and gaps

#### Step 7: Build Comprehensive Synthesis

Now synthesize all findings into the `synthesis.md` file:

**Synthesis approach:**

1. **Identify major themes** across all sources
   - Look for patterns that appear in multiple sources
   - Note areas of consensus and disagreement
   - Group related findings together

2. **Organize synthesis by themes**, not by source
   - Each theme section should integrate insights from multiple sources
   - Compare and contrast different perspectives
   - Build coherent narrative for each theme

3. **For each theme, include:**
   - Core insights and findings (citing source summaries using `[[filename]]`)
   - Supporting evidence and examples from multiple sources
   - Areas of agreement across sources
   - Contradictions or debates (with citations)
   - Practical implications
   - Remaining gaps or open questions

4. **Draw evidence-based conclusions**
   - Only make claims supported by multiple sources
   - Note confidence level based on source quality and consensus
   - Identify areas requiring further research

5. **Create executive summary**
   - Synthesize key findings across all themes
   - Highlight most important insights
   - Note limitations of the research

**Synthesis writing principles:**

- Be comprehensive yet concise—capture all important insights without redundancy
- Cite liberally using `[[source-filename]]` format
- Make connections explicit between different sources and themes
- Distinguish between well-supported findings and tentative conclusions
- Note source quality in your assessments (per the "Evidence Quality Assessment" sections in summaries)

#### Step 8: Quality Review

Verify synthesis quality:

- [ ] All major themes from source summaries are represented
- [ ] Synthesis is organized thematically, not source-by-source
- [ ] Key findings are supported by citations to source summaries
- [ ] Contradictions and debates are identified and explained
- [ ] Conclusions are proportional to evidence strength
- [ ] Executive summary captures essential findings
- [ ] Writing is clear, precise, and information-dense
- [ ] All internal links work
- [ ] YAML frontmatter is complete

#### Step 9: Deliver Results

**Inform user:**
- Location of synthesis and all source summaries
- Summary of major findings and themes
- Note any limitations (inaccessible sources, areas with thin coverage, etc.)
- Highlight any unexpected or particularly significant discoveries

#### Research Approach Characteristics

**Characteristics:**
- Fast execution through simultaneous source investigation
- Efficient use of compute resources
- Requires well-defined research questions and angles upfront

**Best suited for:**
- Well-understood topics with clear structure
- Situations where research angles can be predetermined
- Time-sensitive research needs
- Cases where comprehensive breadth is essential

**Considerations:**
- Research plan should be thorough since pivoting mid-research isn't supported
- Initial source topic selection is critical for comprehensive coverage

---

### Source Quality Guidelines

**Include if:**

- Provides unique insights or data
- Represents authoritative voice
- Offers contrarian or edge perspectives
- Contains primary research or original analysis

## Verification

Upon completion:

1. Confirm all deliverables are created:
   - `plan.md` with research strategy
   - `synthesis.md` with thematic analysis
   - `summaries/` directory with individual source analyses
2. Verify all internal citations link correctly
3. Check that synthesis is organized thematically, not by source
4. Ensure conclusions are proportional to evidence

## Expected Deliverables

```
[YOUR WORKING DIRECTORY]/
└── [RESEARCH TOPIC]/
    ├── summaries/
    │   ├── source-1-summary.md
    │   └── source-2-summary.md
    ├── plan.md
    └── synthesis.md
```

## Notes

- This command orchestrates multiple `research-analyst` subagents for parallel source investigation
- Templates are located in `plugins/dot-claude/commands/templates/`
- The `analyzing-source` skill provides the analysis framework used by research-analyst
- Research quality depends on source accessibility and search result quality