deep-research

• Web search is the core capability of this skill. If the environment has no web access, halt immediately and tell the user.
• Every claim must cite a source URL. Unsourced assertions are not findings — they are guesses.
• Critical claims (market size, growth rates, competitive positioning...) require 2+ independent sources or get confidence: Low.
• Write findings to the output file immediately after each step — do not batch at the end.
• Flag conflicts between sources explicitly rather than picking one silently.
• Prose-first: Write in full sentences and paragraphs (aim for ≥80% prose). Use bullets only for true lists — never as the primary content delivery. "The market reached $4.2B in 2024 [Source]" is better than "* Market: $4.2B".
• Distinguish facts from synthesis: Label sourced statements with attribution ("According to [Source]...") and analytical conclusions with hedges ("This suggests...", "The pattern across sources indicates..."). Never present inference as fact.
• Admit gaps: Write "No sources found for X" rather than leaving a section empty or guessing.

Load these files at the steps indicated only — not all upfront.

The skill uses a dual-output structure in ./research/:

• Flat report: ./research/{date}-{type}-{topic}.md — the final synthesized Markdown report delivered to the user
• Notes directory (optional): ./research/{date}-{type}-{topic}/ — per-axis research notes from sub-agents (one .md file per axis). Create this when using parallel fan-out (Steps 2–4). The agent decides when to use the directory; both can exist simultaneously.

Example:

research/
├── 2025-01-15-market-ai-coding-assistants.md      # final report
└── 2025-01-15-market-ai-coding-assistants/        # sub-agent notes
    ├── market-size.md
    ├── pricing-models.md
    ├── competitive-landscape.md
    └── customer-segments.md

First, get today's date: date +%Y-%m-%d. Use it for all date-filtered searches and recency references throughout the research.

Check for existing research: Look in ./research/ for reports on this topic. If found, summarize what they cover and ask: extend, update, or start fresh?

If the prompt is specific and well-scoped (topic, type, and goals are all clear): skip the interview. Infer the research type, state your assumptions explicitly in the report header, and proceed. Example header note:

Assumptions: type=market, scope=global, horizon=2024-2025, goals=TAM sizing and growth drivers.

If the prompt is vague or ambiguous (e.g., "Research blockchain", "Tell me about AI"): ask the user:

1. What type? (see list below)
2. What specific questions or goals should the research answer?
3. Any geographic, time, or segment constraints?

Research types:

• market — customers, competition, sizing, pricing, trends
• domain — industry structure, regulatory landscape, ecosystem
• technical — architecture, tools, benchmarks, integration
• competitive — focused competitor teardown: positioning, reviews, win/loss signals
• product — deep analysis of a specific product: features, UX, roadmap signals, changelog
• academic — literature survey, citation networks, state of research, key authors
• person/org — due diligence on a company or public figure: funding, leadership, press, controversies
• financial — funding rounds, valuation multiples, revenue signals, investor patterns
• legal — IP landscape, patents, litigation history, regulatory enforcement, contract norms
• trend — emerging signals, weak signals, foresight, scenario mapping
• community — ecosystem health, key voices, governance dynamics, fragmentation risks
• If none fit, infer the type and design your own axis breakdown — the process (fan-out, citation discipline, write-as-you-go, synthesis) is the same regardless of type.

Set output paths:

• Report: ./research/{date}-{type}-{topic}.md (lowercase, hyphens; date first, then type, then topic; under 50 chars for topic portion)
• Notes directory (if using parallel fan-out): ./research/{date}-{type}-{topic}/

Ask if the user wants a different path. Load assets/report-template.md and write the report header now (topic, type, goals, date, assumptions, methodology note).

Load references/citations.md, references/parallel-search.md, and references/researcher.md. Load the type-specific reference file.

Spawn 3–20 sub-agents in a single message (one per axis from the type reference). Each agent:

• Reads references/researcher.md first
• Searches its axis on the web and fetches the sources it cites
• Writes findings as prose paragraphs with inline citations — not bullet lists
• Returns URL, accessed date, and confidence level per claim
• Tags each source: Primary (official docs, filings, peer-reviewed), Established (major publications, analyst firms), or Low (blogs, forums, single opinions). Flag Low-tier sources prominently.
• Critical claims need 2+ sources or get confidence: Low
• Flags conflicts between sources explicitly
• Does not wait for other agents
• Writes output to {notes-dir}/{axis}.md (e.g., ./research/2025-01-15-market-ai-coding-assistants/market-size.md)

Sub-agent prompt template (use exactly this format):

You are a research analyst. Your task: research one specific axis of a larger study.

**Topic:** {overall topic}
**Your axis:** {axis name and description}
**Research goals:** {what specific questions to answer on this axis}
**Geographic/time constraints:** {any from scope interview, or "none"}

Instructions:
1. Run web searches and fetch the relevant source pages.
2. For each finding, note the source URL, access date, and confidence level (High/Medium/Low per the ladder in researcher.md).
3. Tag each source: **Primary** (official docs, government filings, peer-reviewed papers), **Established** (major publications, analyst firms with editorial process), or **Low** (blogs, forums, single opinions). Flag Low-tier sources visibly.
4. Critical claims (numbers, market share, projections) need 2+ sources or get confidence: Low.
5. Flag any conflicts between sources explicitly — do not silently pick one.
6. The axis definition is a starting point, not a ceiling. If you find relevant information that falls outside the stated axis but adds meaningful insight for the overall topic, include it — label it clearly and explain why it matters.
7. External files (PDFs, datasets, analyst reports, regulatory filings, whitepapers, charts) may contain valuable data. When encountered, their key content should be summarized inline — do not leave them as bare links. The `curl` command is available for local downloads when needed.
8. Write findings as **prose paragraphs**, not bullet lists. Embed figures in sentences: "The market reached $4.2B in 2024 [Source]" rather than "* Market: $4.2B". Bullets are acceptable only for true enumerated lists (product names, compliance items, enumerated steps).
9. Distinguish sourced facts from your analysis: use "According to [Source]..." for direct findings and "This suggests..." or "The pattern indicates..." for your synthesis. Never present inference as fact.
10. If a topic cannot be found, write "No sources found for X" — do not guess or leave a blank.
11. Return your findings as a Markdown section ready to paste into a report.

Confidence ladder:
- High: 2+ reputable independent sources agree
- Medium: 1 reputable source (Primary or Established tier)
- Low: blog, forum, single opinion, Low-tier source, or inferred

Citation format: [Source Name](url) (accessed YYYY-MM-DD, confidence: High|Medium|Low, tier: Primary|Established|Low)

Output format:
## {Section heading}
{Prose paragraphs with inline citations. Bullets only for true lists.}

> Conflicts noted: {if any}
> Gaps: {what you couldn't find}

**As a first step, you must read {path_to_skill}/references/researcher.md for instructions on how to conduct research.**

Save your output notes to {absolute path to notes-dir}/{axis}.md

Example for a market research axis:

**Topic:** AI coding assistants market
**Your axis:** Market size and growth (TAM/SAM/SOM, historical growth, projections)
**Research goals:** What is the total addressable market? How fast is it growing? What are the key segments?
**Geographic/time constraints:** Global, 2020-2025

In order to ensure research is conducted as quickly as possible, spawn all sub-agents in parallel (single message with multiple Agent tool calls).

As sub-agents complete, immediately append their findings to the output report file under the appropriate section heading from assets/report-template.md. Do not wait for all agents to finish before writing.

Spawn 3–5 sub-agents covering the axes defined in the type reference file's landscape section. Same citation discipline. Each writes to {notes-dir}/{axis}.md. Append results to the output report file immediately.

Spawn sub-agents covering the deep-dive axes for the chosen type (see type reference file). Same process. Append results immediately.

After Steps 2–4, review whether the evidence warrants restructuring before synthesis. Ask:

• Did findings contradict the initial scope assumptions?
• Did an important angle emerge that wasn't in the original plan?
• Are any sections underpowered by evidence — or overloaded?

If yes: adapt the outline. Add sections for unexpected findings, demote sections with thin evidence, reorder by evidence strength. Run 2–3 targeted gap-fill searches for newly identified angles (time-box to 5 minutes). Document what changed and why in the report's methodology note.

Skip in quick and standard modes.

Use ultrathink here (standard and deep modes).

Read the full output report file (which now contains all appended findings from Steps 2–4). Write the synthesis section:

## Key Findings

(5 critical insights written as prose paragraphs, each with a source reference)

## Strategic Recommendations

1. [Recommendation] — Rationale. Evidence: [source].
2. ... (3–5 recommendations, ranked by impact)

## Risks and Uncertainties

- Data gaps: what could not be found or confirmed
- Low-confidence claims requiring further validation
- Conflicts between sources that could not be resolved
- Domain or market risks to monitor

## Next Steps

- Recommended follow-up research
- If the initial request is not fulfilled, loop on step 1 and ask more questions
- Decisions this research enables

Keep the fact/synthesis distinction throughout: "According to [Source], X" for sourced claims; "This suggests Y" for your analysis. If a recommendation rests on Low-confidence data, say so explicitly.

Critique pass (deep mode only): Before finalizing, red-team the synthesis. Ask: What's missing? What could be wrong? What alternative explanations exist? What biases might be present? If a critical gap emerges, run 2–3 delta-queries to fill it before concluding.

Spawn a single report-writer sub-agent to produce the final polished report. This keeps the coordinator's context clean.

Use the Agent tool with subagent_type="general-purpose" and run_in_background=false:

Agent(
  run_in_background=false
  subagent_type="general-purpose",
  description="Write final report",
  prompt="Read the notes in {absolute path to notes-dir}/ and the current report at {absolute path to report-file} and synthesize into a final research report that answers: {the user's original question in full}.

Earlier research in this conversation to build on: {absolute paths of the earlier report and notes folder from Step 1, or "none"}

Save your final report to this exact path: {absolute path to report-file}

**As a first step, you must read {path_to_skill}/references/report-writer.md for instructions on how to write your research report.**"
)

After the report writer completes, the report at ./research/{date}-{type}-{topic}.md is final.

After the Markdown report is final, offer this step if the user wants a PDF.

Try each tool in order, stop at the first that works:

1. Pandoc (best output quality):

   Copy

   pandoc report.md -o report.pdf --pdf-engine=wkhtmltopdf
   # or with weasyprint:
   pandoc report.md -o report.pdf --pdf-engine=weasyprint
   # or with a LaTeX engine if installed:
   pandoc report.md -o report.pdf

2. md-to-pdf (Node, no LaTeX required):

   Copy

   md-to-pdf report.md

Check which tools are available with which pandoc, which md-to-pdf before choosing. If neither is available, tell the user which to install.

This skill supports MCP connectors for extending research beyond web searches:

Examples of Public Open Knowledge MCP:

• arxiv-mcp: Search academic papers by subject, author, date, or citations. Returns abstracts, PDF links, and citation graphs.
• reddit-mcp: Access subreddit data — top posts, comments, discussion threads. Good for community insights and developer sentiment.
• serp-mcp: Wraps search engines (Google, Bing, DuckDuckGo) to return structured results: titles, snippets, URLs, related questions.

Examples of Private Data MCP:

• gmail-mcp: Queries email threads, attachments, senders, dates. Requires OAuth read-only scope.
• notion-mcp: Accesses databases, pages, and their properties. Searchable by title, content, last edited, or custom properties.
• confluence-mcp, sharepoint-mcp, or custom wiki MCPs for internal knowledge bases.

MCP in the Research Workflow:

• Spawn sub-agents against different MCP endpoints in parallel (Step 2 fan-out)
• When an MCP returns no results, flag the evidence gap explicitly per critical rule #7
• Critical claims from a single MCP source get confidence: Low per critical rule #4 except if from private high-value sources
• MCP data counts as Primary tier if from official docs/filings, Established if from major publications, Low if from blogs/forums

• Additional research limit: Step 5 (additional round) can only be followed once. After those researchers finish, you MUST move directly to Step 6 (report writer). Output: "After these researchers finish, I will move directly to coordinating the report writer."
• No fabrication: If a source does not exist, say so and flag the gap.
• No silent picking: Conflicting sources must be reported, not resolved silently.
• No batching: Write to the file after each step, not at the end.
• No over-claiming: Hedge explicitly on Low-confidence data.
• No inference as fact: Label analytical conclusions with "This suggests..." or similar.
• No diving without scoping: For vague prompts, always scope first — an ambiguous topic produces an unfocused report.

Research reflects a snapshot in time. Web content changes. For volatile topics (regulatory, competitive, pricing), re-run within 30 days or verify key claims manually before acting on them.