| name | deep-research |
| description | In-depth research on technical topics using web search, documentation, and codebase analysis. Use when asked to 'research', 'investigate', 'find out about', 'look into', 'dig into', 'compare X vs Y', 'what's the best library for', 'how does X work', 'should we use', 'find alternatives to', 'evaluate options for', 'what are others doing for', or explore unfamiliar technologies, libraries, or architectural patterns. Also triggers for technology evaluation, migration research, and dependency decisions. NOT for quick brainstorming (use /brainstorm), NOT for feature discovery (use /nf), NOT for static code analysis (use /code-analysis). |
| argument-hint | [topic or question] |
| context | fork |
| allowed-tools | ["WebSearch","WebFetch","Read","Grep","Glob","Task","mcp__exa__web_search_exa","mcp__exa__get_code_context_exa","mcp__ref__ref_search_documentation","mcp__ref__ref_read_url"] |
Deep Research
Announcement: Begin with: "I'm using the deep-research skill for in-depth technical research."
Overview
Conduct comprehensive research on technical topics, synthesizing information from multiple sources. Since this runs in a forked context, explore extensively — only the final findings return to the main conversation.
1. Determine Research Depth
Not every request needs a 10-source report. Match the depth to the question:
| Depth | When | Output |
|---|
| Quick | Simple factual question, "how do I X", single-topic lookup | Direct answer with 1-2 sources |
| Comparison | "X vs Y", "which library for", "should we use" | Comparison table + recommendation |
| Deep | Technology evaluation, migration analysis, architectural decision | Full structured report |
If the user's intent is ambiguous, default to Comparison — it's the most common need.
2. Source Strategy
Tool Priority (Exa-first)
Pick the smallest set of tools that answers the question. Many Quick-depth queries need zero tool calls. When you do search, choose by fit:
get_code_context_exa when you need API/library code examples or usage patterns.web_search_exa when the question is conceptual, comparative, or ecosystem-wide.ref_search_documentation / ref_read_url when you need authoritative confirmation and Exa's summary is insufficient.WebSearch / WebFetch only as a fallback when the above can't reach the source.
Do not run a tool to confirm something you already know confidently from the docs or the codebase — cite the source instead.
Parallel Search
Since this runs in a fork, optimize for speed by launching parallel queries:
- When queries have no dependencies, emit all of them in the same assistant turn (one tool-use block per query). Do not wait for the first to return before issuing the next.
- Combine web searches with a local
Grep/Glob pass in the same turn when codebase context is relevant.
- Use multiple small, focused queries rather than one broad query
Source Types
| Source | Best For |
|---|
| Official docs | Authoritative API/config info |
| GitHub repos | Real implementations, issue discussions, activity signals |
| Technical blogs | Best practices, gotchas, real-world experience |
| Stack Overflow | Common problems, community-vetted solutions |
| Local codebase | Integration points, existing patterns, constraints |
3. Research Strategies
Technology Evaluation:
- Official documentation overview
- GitHub — stars, recent activity, open issues, release cadence
- Comparison articles (vs alternatives)
- Real-world adoption signals (who uses it, at what scale)
- Local codebase — integration points, migration effort
Problem Solving:
- Error message / symptom search (Exa code context)
- GitHub issues in relevant repos
- Stack Overflow discussions
- Official troubleshooting guides
- Local codebase — similar patterns or workarounds
Best Practices:
- Official style guides and recommendations
- Community conventions (popular repos, conference talks)
- Existing patterns in our codebase
- Project preferences (read from CLAUDE.md)
4. Cross-Verification
- Match source count to depth: Quick = 1–2 sources (skip Cross-Verification entirely); Comparison = 2–3; Deep = 3–5.
- Stop gathering once the answer is stable across sources — additional confirmatory sources add little value. If the first 2 sources agree and are authoritative (official docs, primary repos), that's enough.
- Verify claims against official docs only when the claim is load-bearing for a recommendation.
- Check publication dates — prefer content from the last 12 months
- Look for consensus; flag disagreements explicitly
- Be skeptical of AI-generated content in search results
5. Output Format
Adapt output to the research depth determined in step 1.
Quick Answer
**Answer**: [concise answer]
**Source**: [url] — [what it confirmed]
**Caveat**: [any important limitations or conditions]
Comparison
## [X] vs [Y] for [use case]
| Criteria | X | Y |
|----------|---|---|
| [criterion] | [assessment] | [assessment] |
**Recommendation**: [which and why, considering our project context]
**Sources**: [urls]
Full Report
# Research: [Topic]
**Question**: [what was investigated]
**Date**: [ISO date]
**Sources**: [count]
## Summary
[3-5 sentences answering the research question]
## Findings
### [Finding title]
**Confidence**: HIGH / MEDIUM / LOW
**Sources**: [list]
[details]
## Recommendations
1. [recommendation with rationale]
2. [recommendation with rationale]
## Sources
- [Source](url) — [what it provided]
## Open Questions
- [anything unresolved]
6. Project Context
Instead of relying on a static list, read project context dynamically:
- Check
CLAUDE.md at the repo root for current stack and architecture
- Check
{{DOCS_DIR}}/AGENTS.md for project-specific constraints
- Check
package.json / tsconfig.json for actual dependencies and versions
- Reference existing patterns in the codebase when making recommendations. If you cite a file or function, open it with
Read first — do not speculate about code you have not read.. If you cite a file or function, open it with Read first — do not speculate about code you have not read.
This ensures recommendations stay aligned with the project as it evolves.
7. Before Returning
