deep-research

name

deep-research

description

Use for deep, multi-source research, tool/library/vendor evaluation, X vs Y comparisons, state-of-the-art surveys, standards/spec analysis, architecture research, and decision briefs. Use when the user asks to research something deeply, compare options, evaluate whether to use a tool, investigate current best practices, summarize the state of a topic, or write a research brief. For a single quick lookup or one fact with a citation, use the exa-web-search skill instead.

Deep Research

Turn a broad or decision-heavy question into source-backed, decision-ready research. Use Exa-backed search for discovery, fetch for reading specific sources, DeepWiki for GitHub-project documentation, local repo tools for codebase context, and gh when the research concerns GitHub repos, issues, PRs, releases, or project health.

This is not just web search. The job is to scope the question, gather credible sources, cross-check claims, separate facts from interpretation, and produce a useful recommendation with confidence and caveats. For a single quick lookup, defer to the exa-web-search skill — this skill is for multi-source investigation and synthesis.

Tool Use (Pi MCP)

• Use mcp_exa_web_search_exa for discovery: current sources, official docs, competing views, papers, specs, release notes, issues, benchmarks, examples.
• Use mcp_exa_web_fetch_exa for retrieval: read actual pages before relying on them.
• Use mcp_deepwiki_* (read_wiki_structure, read_wiki_contents, ask_question) when researching a public GitHub library/framework — it returns structured documentation that raw search/gh cannot.
• Use repo tools (read, grep, find, ls) when the research depends on the current codebase.
• Use the gh CLI (via bash) when researching GitHub repos, PRs, issues, releases, maintainers, labels, discussions, or project activity.
• Do not rely on search-result snippets as evidence for important claims. Fetch and read the source.

If the Exa MCP tools are not available, run mcp_list to check connected servers. Exa needs EXA_API_KEY (sourced from ~/.pi/agent/.env); if it is missing, tell the user discovery is limited to mcp_exa_web_fetch_exa on known URLs until the server is connected, and proceed with what is reachable.

Choose The Mode

Use fast path for narrow factual questions. Use full research mode for decisions, tradeoffs, competing options, unclear evidence, risk, architecture, vendor/tool choice, or broad technical topics.

Fast path examples:

• "Does Pi support Exa web search?"
• "How do I configure the DeepWiki MCP?"
• "Is this library still maintained?"
• "What changed in React 19?"
• "Find the official docs for this setup."

(For these single-lookup questions, exa-web-search is often the better fit — use fast path here only when it's clearly part of a larger research task.)

Full research examples:

• "Should we use Temporal or BullMQ?"
• "Research the best approach for multi-agent coding workflows."
• "Compare vector databases for our use case."
• "What is the state of the art in browser-use agents?"
• "Evaluate this vendor before we adopt it."

Fast Path Workflow

Use fast path when the question can be answered from one to three authoritative sources.

1. Search only if the authoritative URL is not already known.
2. Fetch one to three high-quality sources.
3. Answer directly in one to three short paragraphs.
4. Cite the evidence briefly.
5. Stop. Do not produce large tables or a full research brief.

Fast path output:

**Answer**
{direct answer}

**Evidence**
- {Source}: {what it confirms}
- {Source}: {what it confirms}

**Caveat**
{optional version/date/uncertainty note}

**Next Step**
{optional concrete action}

Omit Caveat or Next Step if they are not useful.

Full Research Workflow

Follow this order for deep research.

1. Scope The Question

Identify:

• The decision or question being answered.
• The user's likely constraints: stack, budget, timeline, scale, risk tolerance, maturity needs, compliance, team skill, and deployment environment.
• The required depth: quick recommendation, comparative analysis, technical brief, implementation plan, or adoption/risk assessment.

Ask one concise clarifying question only when the answer materially depends on a missing constraint. If reasonable assumptions are enough, state them and proceed.

2. Discover Sources

Search for a mix of source types:

• Official docs and API references.
• Specs, standards, RFCs, or design docs.
• Release notes, changelogs, migration guides, and deprecation notices.
• GitHub repositories, issues, discussions, and PRs.
• Academic papers or technical reports.
• Maintainer posts and reputable engineering writeups.
• Benchmarks with methodology, not just headline numbers.
• Critical viewpoints, incident reports, and known limitations.

Prefer primary sources. Use vendor marketing pages only for claims about vendor positioning, pricing, packaging, or stated capabilities. Corroborate technical claims elsewhere.

3. Read And Verify

For important claims:

• Fetch and read the source.
• Check publication or update date.
• Check software version, API version, model version, or benchmark date.
• Cross-check across at least two independent sources when the claim affects the recommendation.
• Look for disagreement, stale advice, hidden assumptions, and benchmark flaws.

Do not present a claim as fact if it only appears in a single weak source. Mark it as low confidence or unverified.

4. Evaluate Options

When comparing tools or approaches, evaluate dimensions that matter in practice:

• Fit to the user's constraints and use case.
• Maturity and maintenance activity.
• API ergonomics and integration complexity.
• Operational burden and failure modes.
• Performance, scalability, and reliability evidence.
• Security, privacy, and compliance implications.
• Portability and lock-in.
• Cost and licensing.
• Ecosystem, community, docs, and support.
• Migration path and reversibility.

Do not over-weight popularity metrics. Stars, downloads, and social buzz are weak signals unless backed by maintenance and adoption evidence.

5. Synthesize

Separate:

• Facts directly supported by sources.
• Interpretation based on multiple facts.
• Recommendations based on the user's constraints.
• Unknowns that need hands-on validation.

Prefer a clear recommendation over a neutral summary when the evidence supports one. If evidence is mixed, say what decision would change under which constraint.

Full Research Output

Use this structure by default:

# Research Brief: {topic}

## Bottom Line
{1-3 sentence answer}

## Recommendation
{recommended path, including when not to use it}

## Context
{question, constraints, assumptions, and scope}

## Findings
| Finding | Evidence | Confidence |
| --- | --- | --- |
| {claim} | {source-backed support} | {High/Medium/Low} |

## Options Compared
| Option | Pros | Cons | Best Fit | Risks |
| --- | --- | --- | --- | --- |
| {option} | {pros} | {cons} | {fit} | {risks} |

## Source Notes
- {Source title/link}: {why it matters, date/version if relevant}

## Unknowns
- {uncertainty or unverifiable point}

## Next Steps
- {experiment, decision, proof of concept, or implementation step}

If there is only one viable option or no comparison is needed, omit Options Compared and explain why.

Source Quality Rules

• Prefer official docs, specs, papers, release notes, changelogs, maintainers, source code, and issue trackers.
• Treat AI-generated summaries, SEO pages, listicles, and vendor claims as low-confidence unless corroborated.
• Check whether docs refer to the current version.
• Check whether benchmark methodology matches the user's likely workload.
• Do not infer production readiness from a demo alone.
• Do not cite sources you did not read.
• Include dates and versions when recency matters.
• If source access fails, say so and avoid pretending to know what it says.

GitHub Project Health Checks

When evaluating an open source project, inspect:

• Recent releases and changelog quality.
• Open issue volume, age, maintainer responses, and recurring bug themes.
• PR activity, review latency, and merge pattern.
• Security policy, license, governance, and bus factor signals.
• Documentation quality and migration guides.
• Breaking-change history and deprecation discipline.

Use gh (via bash) for GitHub-hosted projects, and mcp_deepwiki_ask_question for a fast read on a repo's architecture and docs. Do not treat star count as a primary health metric.

Guardrails

• Do not fabricate citations, numbers, benchmarks, release dates, or quotes.
• Do not bury the answer under raw notes. Synthesize.
• Do not present marketing claims as technical proof.
• Do not turn every narrow question into a full research report — for a single lookup, exa-web-search is the right skill.
• Do not ask multiple clarification questions unless the user requested a collaborative research plan.
• If the answer depends on live information and live search is unavailable, state that limitation clearly.

Reporting Style

• Be concise but evidence-backed.
• Use links or source names in evidence sections.
• Use confidence labels: High, Medium, Low.
• Lead with the answer before the research trail.
• Make the next step concrete: decide, test, prototype, wait, avoid, migrate, or gather a missing piece of evidence.