deep-research

What this skill does

# Deep Research Command

You are orchestrating a **multi-agent deep research workflow** that produces comprehensive, well-cited research reports.

## Command Workflow

When the user invokes `/stepwise-research:deep-research <topic>`, follow these steps:

### 1. Clarification Phase (Only if Needed)

If the research topic is **ambiguous or unclear**, ask 1-2 clarifying questions using the AskUserQuestion tool:
- What specific aspect should be prioritized?
- What timeframe or context is relevant?
- Are there specific sources to include/exclude?

**Skip this step if:**
- Topic is explicit (e.g., "research Docker containerization security")
- User has provided clear context
- Query is self-contained

### 2. Analyze Query Complexity

Determine the complexity level of the research query to decide how many workers to spawn:

**Query Types:**
- **Simple definition** (e.g., "What is Docker?"): 1 worker
- **How-to guide** (e.g., "How does JWT work?"): 1-2 workers
- **Comparison (2 items)** (e.g., "React vs Vue"): 2-3 workers
- **Comparison (3+ items)** (e.g., "Compare top 5 databases"): 3-5 workers
- **State-of-the-art** (e.g., "Current state of WebAssembly"): 4-6 workers
- **Multi-faceted analysis** (e.g., "Analyze enterprise AI adoption"): 5-8 workers
- **Controversial topic** (e.g., "Pros and cons of microservices"): 4-6 workers (ensure balanced perspectives)

### 3. Generate Sub-Questions

Break the research query into 2-6 focused sub-questions based on complexity:

**Example for simple query** ("What is Docker?"):
- Sub-question 1: What is Docker and what problem does it solve?

**Example for comparison** ("PostgreSQL vs MySQL"):
- Sub-question 1: PostgreSQL architecture and performance characteristics
- Sub-question 2: MySQL architecture and performance characteristics
- Sub-question 3: Real-world benchmarks and case studies comparing both

**Example for complex research** ("State of WebAssembly adoption"):
- Sub-question 1: WebAssembly capabilities and features in 2026
- Sub-question 2: Major frameworks and tools supporting WebAssembly
- Sub-question 3: Enterprise adoption case studies and success stories
- Sub-question 4: Performance benchmarks and limitations
- Sub-question 5: Security considerations and best practices
- Sub-question 6: Future roadmap and emerging use cases

**Guidelines:**
- Each sub-question should be independently researchable
- Together they should provide comprehensive coverage
- Avoid overlapping questions
- Focus on different aspects or perspectives

### 4. Spawn Research Workers in Parallel

Use the `Task` tool to spawn multiple `stepwise-research:research-worker` agents **in a single message** to enable parallel execution.

**Critical:** All worker spawns MUST be in the same response to enable parallel execution.

For each sub-question, spawn a worker:

```
Task:
  subagent_type: "stepwise-research:research-worker"
  description: "Research [sub-question summary]"
  prompt: "Research the following focused question:

  Question: [sub-question]
  Context: [relevant context from main query]

  Instructions:
  - Execute 3-5 web searches with progressively refined queries
  - Start broad (1-6 word queries) then narrow based on results
  - Fetch full content from 5-10 promising sources
  - Prioritize .gov, .edu, peer-reviewed, and official documentation
  - Return compressed findings with citations in this format:

  ## Findings: [Sub-Question]

  ### Key Insight 1: [Title]
  [2-4 sentence summary]
  **Sources:** [1] [2]

  ### Key Insight 2: [Title]
  [2-4 sentence summary]
  **Sources:** [3] [4]

  [Continue for 3-6 key insights]

  ## Bibliography
  [1] Source Title - URL
  [2] Source Title - URL
  ...

  ## Research Metadata
  - Queries executed: [N]
  - Sources fetched: [M]
  - Coverage assessment: [Complete | Partial | Limited]
  - Gaps identified: [Any areas needing follow-up]
  "
```

Repeat this Task call for each sub-question in the same message.

### 5. Monitor Worker Progress

Wait for all workers to complete. Each worker will:
- Execute 3-5 web searches with progressively refined queries
- Fetch full content from 5-10 sources
- Compress findings into 3-6 key insights
- Return structured findings with citations

**Do not proceed to synthesis until all workers have completed.**

### 6. Synthesize Findings

After all workers complete, synthesize their findings into a coherent research report:

**Synthesis Process:**
1. **Read all worker outputs** from the task results
2. **Identify themes** across worker findings:
   - What patterns emerge?
   - What do multiple sources agree on?
   - What contradictions exist?
3. **Cross-reference findings:**
   - Map insights to multiple sources
   - Flag claims supported by only one source
   - Identify areas of consensus vs disagreement
4. **Detect gaps:**
   - Are there important aspects not covered?
   - Are some claims weakly supported?
   - Do we need additional research?

**If critical gaps exist:**
- Spawn 1-2 additional workers with targeted questions
- Wait for their findings
- Incorporate into synthesis

**Don't over-research:** If you have 10-15+ quality sources and coverage of main themes, proceed to report generation.

### 7. Generate Research Report

Use the `generate-report` script to create the report with proper YAML frontmatter and structure.

**Step 7a: Synthesize content**

Before calling the script, prepare the content for each section:

1. **Executive Summary**: 3-5 sentence overview answering the research question directly
2. **Detailed Findings**: Organized by theme with subsections, citing sources as `[N]`
3. **Cross-References and Contradictions**: 2-3 paragraphs discussing areas of consensus, disagreements between sources, and evolution of thinking on the topic
4. **Conclusions**: 3-5 bullet points summarizing key takeaways
5. **Bibliography**: Numbered list `[N] Source Title - URL`

**Quality Guidelines:**
- **Synthesis, not concatenation:** Don't just copy-paste worker findings. Weave them into a coherent narrative.
- **Multiple citations per claim:** Aim for 2-3 sources per major claim.
- **Balanced perspectives:** Include contrarian views if they exist.
- **Source diversity:** Mix .gov, .edu, industry blogs, official docs.
- **Clarity:** Write for a technical audience but explain jargon.
- **No fluff:** Every sentence should provide value.

**Step 7b: Generate report file**

Compute the sanitized filename:
- Convert topic to lowercase
- Replace spaces with hyphens
- Remove special characters (keep only alphanumeric and hyphens)
- Truncate to 60 characters max
- Append date suffix: `[sanitized-topic]-YYYY-MM-DD.md`

Then call the script:
```bash
research/skills/deep-research/scripts/generate-report \
  --title "Research on [Topic]" \
  --query "[Original research question]" \
  --keywords "[keyword1,keyword2,keyword3,...]" \
  --agent-count [N] \
  --source-count [M] \
  --output-file "thoughts/shared/research/[sanitized-topic]-[YYYY-MM-DD].md" \
  --executive-summary "[synthesized executive summary]" \
  --findings "[synthesized detailed findings with citations]" \
  --cross-references "[cross-references and contradictions analysis]" \
  --conclusions "[synthesized conclusions]" \
  --bibliography "[numbered bibliography entries]"
```

**All parameters are required except** `--executive-summary`, `--findings`, `--cross-references`, `--conclusions`, and `--bibliography` (which are optional but should always be provided for a complete report).

The script:
- Validates required parameters
- Generates YAML frontmatter (title, date, query, keywords, status, agent_count, source_count)
- Creates the report with all sections
- Adds a generation timestamp footer
- Creates parent directories if needed

### 8. Citation Verification

After generating the report, spawn the `stepwise-research:citation-analyst` agent:

```
Task:
  subagent_type: "stepwise-research:citation-analyst"
  description: "Verify citations"
  prompt: "Analyze the research report at [report_path