Deep Research

Never edit this file directly. To make additions or modifications, edit the appropriate section in ./vstack.toml. Then run vstack refresh.

Deep Research

Use this skill for evidence-backed research reports, architectural investigations, vendor/library comparisons, technology choices, and workflow-owned findings.md reports.

Harness Routing

Rules

• Always use Exa for deep research. Do not substitute general web search unless Exa is unavailable and the user explicitly approves a fallback.
• For workflow-owned research, write findings.md to the requested research docs path exactly.
• Include citations/source URLs in every findings report.
• Keep findings.md clean and human-readable; preserve raw Exa metadata in a sidecar JSON file (findings.raw.json by default when --output findings.md is used). Evidence excerpts must be sanitized so source Markdown headings do not render as large quoted headings.
• Once the requested report and raw sidecar exist, run deep-research validate <findings.md> <findings.raw.json> (see § Validation) and stop. Do not add local reproduction, benchmark, test, code-inspection, or implementation work unless the caller explicitly requested local validation in addition to Exa research.
• If EXA_API_KEY is missing, fail with clear setup instructions. EXA_API_KEY may be a direct key or a 1Password op://vault/item/field reference when the op CLI is installed and signed in.
• Use --mode standard by default. Use --mode lite for fast spikes and --mode full for strategic/high-risk decisions. Explicit --type, --num-results, and --text-max-characters override mode defaults.
• Use one adaptive findings format for all modes. The mode changes depth/source volume and Exa content settings, not the required report sections; record mode and source counts in ## Research Metadata.
• In Pi, web_research uses Exa /search with deep search type, systemPrompt, text extraction, highlights, and, for standard/full, summaries plus structured outputSchema. lite avoids the default schema because live Exa deep-lite tests returned empty result sets when structured output was requested. Project/user settings may override mode profiles via pi-web-tools.exaResearchModes.

Script Usage

skills/deep-research/scripts/deep-research report "question" --mode standard --output path/to/findings.md
skills/deep-research/scripts/deep-research report --query-file prompt.txt --context-glob 'context-*.md' --mode full --output findings.md
skills/deep-research/scripts/deep-research json "question" --output raw.json
skills/deep-research/scripts/deep-research validate findings.md findings.raw.json
skills/deep-research/scripts/deep-research doctor

Modes (Exa /search caps: numResults 1-100, text.maxCharacters 1-10000, additionalQueries max 10):

--additional-query semantics (recorded in metadata — verify with validate):

Sidecar metadata records queryCount (distinct queries: 1 primary + additional), requestCount (Exa API calls), the additionalQueries list, and synthesis (whether a synthesized answer came back).

Common flags:

• --mode lite|standard|full
• --research-mode lite|standard|full (alias)
• --type deep-reasoning|deep-lite|deep
• --output <path>
• --query-file <path>
• --context <path> repeatable
• --context-glob <glob> simple sorted file glob, e.g. context-*.md
• --system-prompt <path-or-text>
• --additional-query <query> repeatable
• --include-domain <domain> repeatable
• --exclude-domain <domain> repeatable
• --start-date YYYY-MM-DD
• --end-date YYYY-MM-DD
• --num-results <n>
• --text-max-characters <n>
• --raw-output <path> (defaults to findings.raw.json next to --output for report mode)
• --no-raw-output
• --timeout <seconds>

Task-Type Recipes

Choosing Flag Values

• --num-results: more results = more noise exposure, not better synthesis. 10-25 for targeted questions; 50 (standard default) for decision research; 100 only for landscape scans where you will prune sources.
• --text-max-characters: caps extracted text per result (Exa max 10000). Lower it (2000-4000) when many sources are expected and only key claims matter; keep the default for dense primary sources.
• --include-domain is a hard host filter ("results will only come from these domains"), not a quality filter: --include-domain github.com admits any repo, not just reputable ones, and excludes everything else. Name authoritative projects/organizations in the query text for quality, use domain filters only to constrain hosts, and audit the resulting source list either way.
• --additional-query: phrase each as a full natural-language question from a different angle (terminology variant, competing approach, failure mode) rather than keyword permutations.

Validation

After generating a report, run:

skills/deep-research/scripts/deep-research validate path/to/findings.md path/to/findings.raw.json

Prints {ok, errors, warnings, mode, synthesis, queryCount}; exit 0 means no errors. Deterministic checks:

Manual review checks (need judgment; validate cannot perform them):

• Claims contradicted by the returned sources (e.g. complexity classes, benchmark numbers) — spot-check material claims against the cited source text in the sidecar.
• Off-topic sources sharing an acronym or name with the research subject.
• Recommendation assertions with no claim-level support in Evidence and Sources.
• Results generalized beyond what the source established (e.g. a line-chart result applied to candlesticks).

Findings Format

• Template: templates/findings.md
• Format checklist: templates/findings-report-format.md (this is a Markdown format guide, not a machine-readable schema)
• Required report sections: Executive Summary, Key Findings, Evidence and Sources, Tradeoffs / Alternatives, Recommendation / Decision Criteria, Risks / Unknowns, Revisit Conditions, and Research Metadata.
• Do not embed raw Exa JSON in findings.md. Store provider payloads in the sidecar JSON (findings.raw.json by default, or the explicit --raw-output/rawOutputPath).