Research

Deep Research

General-purpose deep research with multi-source synthesis, confidence scoring, source-support auditing, and anti-hallucination verification. The design follows current deep-research patterns: plan before retrieval, start broad then narrow, coordinate parallel workers through a lead agent, audit whether cited sources actually support each claim, use perspective expansion for breadth, and synthesize into a report rather than a source dump.

Canonical Vocabulary

Use these canonical terms exactly in plans, journals, delegated task prompts, and final reports.

Dispatch

Auto-Detection Heuristic

If no mode keyword matches:

1. Ends with ? or starts with question word (who/what/when/where/why/how/is/are/can/does/should/will) → Investigate
2. Contains vs, versus, compared to, or between noun phrases → Compare
3. Declarative statement with factual claim, no question syntax → Fact-check
4. Broad field name with no specific question → ask: "Investigate a specific question, or survey the entire field?"
5. Ambiguous → ask: "Would you like me to investigate this question, verify this claim, or survey this field?"

Plan Gate

Produce a triage packet before substantial retrieval for Standard, Deep, and Exhaustive research:

1. Restate the research question, audience, assumptions, constraints, and high-stakes or private-source risks.
2. Show complexity score, tier, mode, source difficulty, verification complexity, and effort budget.
3. List sub-questions, source families, planned worker lanes, retrieval/extraction capabilities, and degraded-mode limits.
4. State the source-support audit strategy, including how citation anchors and support statuses will be checked.
5. State whether execution continues immediately or pauses for user review.

Pause conditions override continue conditions. Pause for user input when the topic is high-stakes, ambiguous after triage, asks for private or credentialed sources, or the user explicitly requests plan review. When pause is due to user-pivotal scope or audience uncertainty, apply instructions/global.md Depth routing and invoke /grill-me before substantial retrieval. Factual or evidence gaps stay on the research Plan Gate, not grill-me. In noninteractive harnesses, emit the Plan Gate with blockers and stop before substantial retrieval for those pause cases. Continue without waiting only when the question is clear, non-sensitive, and has no pause condition. Quick tier may skip the formal gate but must include a short methodology note in the answer.

Gallery (Empty Arguments)

Present research examples spanning domains:

Pick a number, paste your own question, or type guide me.

Skill Awareness

Before starting research, check if another skill is a better fit:

If the user confirms they want general research, proceed.

For repo-owned CLI skill-first routing (/ffmpeg, /yt-dlp, /trafilatura, /pentest), see the Repo CLI skills table in references/source-selection.md.

Complexity Classification

Score the query on 5 dimensions (0-2 each, total 0-10):

Present the scoring through the Plan Gate for Standard, Deep, and Exhaustive work. User can override tier with --depth <tier>.

Scaling Strategy

Scale work by query complexity and available orchestration capabilities:

Capability resolution: Treat named tools and orchestration APIs as preferred capabilities. Claude Code may use Task/TeamCreate; Codex may use dynamic subagents or parallel tool calls; other agents may use their native delegation or run the wave pipeline serially. If no delegation equivalent exists, use degraded orchestration: preserve wave order, reduce breadth, and report the limitation in methodology. Apply confidence ceilings only when source or retrieval capabilities are unavailable, per references/source-selection.md.

Effort budgeting: Bound every Standard+ run before retrieval. State target worker count, expected source count, search depth, extraction depth, and stop conditions. Start broad, then narrow: Wave 1 maximizes source and perspective coverage; Wave 2 spends depth only on high-value leads; Wave 3 spends verification budget on claims likely to survive synthesis.

Wave Pipeline

All non-Quick research follows this 5-wave pipeline. Quick merges Waves 0+1+4 inline.

Wave 0: Triage (always inline, never parallelized)

1. Run !uv run python scripts/research-scanner.py "$ARGUMENTS" for deterministic pre-scan
2. Decompose query into 2-5 sub-questions
3. Score complexity on the 5-dimension rubric
4. Check tool availability — probe key retrieval, extraction, and delegation capabilities; set degraded mode flags and confidence ceilings per references/source-selection.md
5. Select tools per domain signals — read references/source-selection.md
6. Check for existing journals — if track or resume, load prior state
7. Run the Plan Gate — show: complexity score, sub-questions, source families, worker lanes, support-audit strategy, effort budget, estimated tier, and whether execution continues immediately or pauses. User may override.

Wave 1: Broad Sweep (parallel)

Scale by tier:

Quick (inline): 1-2 tool calls sequentially. No subagents.

Standard (subagent wave): Dispatch 3-5 parallel subagents with the platform's available delegation primitive:

Subagent A → brave-search + duckduckgo-search for sub-question 1
Subagent B → exa + g-search for sub-question 2
Subagent C → context7 / deepwiki / arxiv / semantic-scholar for technical specifics
Subagent D → wikipedia / wikidata for factual grounding
[Subagent E → PubMed / openalex if academic domain detected]

Deep (agent team): Create a research team with the platform's available team primitive:

Lead: triage (Wave 0), orchestrate, judge reconcile (Wave 3), synthesize (Wave 4)
  |-- web-researcher:       brave-search, duckduckgo-search, ddgs, exa, g-search
  |-- tech-researcher:      context7, deepwiki, arxiv, semantic-scholar, package-version-check-mcp
  |-- content-extractor:    fetcher, trafilatura, docling, wikipedia, wayback
  |-- [academic-researcher: arxiv, semantic-scholar, openalex, crossref, PubMed]
  |-- [adversarial-reviewer: devil's advocate — counter-search all emerging findings]

Spawn academic-researcher if domain signals include academic/scientific. Spawn adversarial-reviewer for Exhaustive tier or if verification complexity >= 2.

Exhaustive: Deep team + each teammate runs nested subagent waves internally when supported; otherwise use serial batches and label the run "degraded orchestration."

Each subagent/teammate returns structured findings:

{
  "sub_question": "...",
  "findings": [{
    "claim": "...",
    "confidence": 0.6,
    "evidence": [{"tool": "brave-search", "url": "https://...", "timestamp": "2026-04-24T12:00:00Z", "excerpt": "..."}],
    "cross_validation": "unknown",
    "source_support": [{"url": "https://...", "support_status": "supports|partial|contradicts|irrelevant", "citation_anchor": "...", "support_note": "..."}],
    "bias_markers": [],
    "gaps": []
  }],
  "leads": ["url1", "url2"],
  "gaps": ["could not find data on X"]
}

Wave 1.5: Perspective Expansion (Deep/Exhaustive only)

STORM-style perspective-guided conversation. Spawn 2-4 perspective subagents:

Each perspective agent reviews Wave 1 findings and generates 2-3 additional sub-questions from their viewpoint. These sub-questions feed into Wave 2.

Wave 2: Deep Dive (parallel, targeted)

1. Rank leads from Wave 1 by potential value (citation frequency, source authority, relevance)
2. Dispatch deep-read subagents — prefer /trafilatura on shell harnesses, else fetcher/trafilatura MCP/docling to extract full content from top leads
3. Follow citation chains — if a source cites another, fetch the original
4. Fill gaps — for each gap identified in Wave 1, dispatch targeted searches
5. Build preliminary claim-to-source support rows for each source-backed finding
6. Use thinking MCPs:
   • cascade-thinking for multi-perspective analysis of complex findings
   • structured-thinking for tracking evidence chains and contradictions
   • think-strategies for complex question decomposition (Standard+ only)

Wave 3: Cross-Validation and Source-Support Audit (parallel)

The anti-hallucination wave. Read references/evidence-chain.md, references/confidence-rubric.md, and references/self-verification.md.

For every claim surviving Waves 1-2:

1. Independence check — are supporting sources truly independent? Sources citing each other are NOT independent.
2. Counter-search — explicitly search for evidence AGAINST each major claim using a different search engine
3. Freshness check — verify sources are current (flag if >1 year old for time-sensitive topics)
4. Contradiction scan — read references/contradiction-protocol.md, identify and classify disagreements
5. Source-support audit — classify each claim/source pair as supports, partial, contradicts, or irrelevant
6. Citation anchor verification — fetch cited URLs when possible and confirm the cited passage supports the exact claim, not merely the broad topic
7. Confidence scoring — assign 0.0-1.0 per references/confidence-rubric.md, then cap confidence when support is partial, single-source, contradictory, or degraded
8. Bias sweep — check each finding against 10 bias categories (7 core + 3 LLM-specific) per references/bias-detection.md

Self-Verification (3+ findings survive): Spawn devil's advocate subagent per references/self-verification.md:

For each finding, attempt to disprove it. Search for counterarguments. Check if evidence is outdated. Verify claims actually follow from cited evidence. Flag LLM confabulations.

Adjust confidence: Survives +0.05, Weakened -0.10, Disproven set to 0.0. Adjustments are subject to hard caps — single-source claims remain capped at 0.60 even after survival adjustment.

Wave 4: Synthesis (always inline, lead only)

Produce the final research product. Read references/output-formats.md for templates.

The synthesis is NOT a summary. It must:

1. Answer directly — answer the user's question clearly
2. Map evidence — all verified findings with confidence and citations
3. Show source support — summarize citation anchor status and unsupported or partially supported statements
4. Surface contradictions — where sources disagree, with analysis of why
5. Show confidence landscape — what is known confidently, what is uncertain, what is unknown
6. Audit biases — biases detected during research
7. Identify gaps — what evidence is missing, what further research would help
8. Distill takeaways — 3-7 numbered key findings
9. Cite sources — full bibliography with provenance

Output format adapts to mode:

• Investigate → Research Brief (Standard) or Deep Report (Deep/Exhaustive)
• Fact-check → Quick Answer with verdict + evidence
• Compare → Decision Matrix
• Survey → Annotated Bibliography
• User can override with --format brief|deep|bib|matrix
• Add a chart, matrix, or dashboard artifact only when it clarifies numeric, comparative, temporal, or source-coverage evidence.

Confidence Scoring

Hard rules:

• No claim reported at >= 0.7 unless supported by 2+ independent sources
• Single-source claims cap at 0.6 regardless of source authority
• Degraded mode (all research tools unavailable): max confidence 0.4, all findings labeled "unverified"

Merged confidence (for claims supported by multiple sources): c_merged = 1 - (1-c1)(1-c2)...(1-cN) capped at 0.99

Evidence Chain Structure

Every finding carries this structure:

FINDING RR-{seq:03d}: [claim statement]
  CONFIDENCE: [0.0-1.0]
  EVIDENCE:
    1. [source_tool] [url] [access_timestamp] — [relevant excerpt, max 100 words]
    2. [source_tool] [url] [access_timestamp] — [relevant excerpt, max 100 words]
  CROSS-VALIDATION: [agrees|contradicts|partial] across [N] independent sources
  SOURCE SUPPORT SUMMARY: [verified|partial|unsupported|contradicted] derived from per-source `support_status` rows
  BIAS MARKERS: [none | list of detected biases with category]
  GAPS: [none | what additional evidence would strengthen this finding]

Use !uv run python scripts/finding-formatter.py --format markdown to normalize.

Source Selection

Read references/source-selection.md during Wave 0 for the full tool-to-domain mapping. Summary:

Multi-engine protocol: For any claim requiring verification, use minimum 2 different search engines or independent source families. Fact-checking mode requires 3+ search engines when available. If fewer engines are available, report degraded mode, use the fallback confidence ceilings in references/source-selection.md, and explain the missing retrieval capabilities.

Progressive Disclosure

Load only the next required reference:

1. Start with this file for routing, classification, and wave order.
2. Load references/source-selection.md during Wave 0 only.
3. Load validation references during Wave 3 only: evidence-chain, confidence, contradiction, self-verification, and bias files as needed.
4. Load references/output-formats.md or references/dashboard-schema.md only when producing final output or exports.
5. Never preload all references; summarize tool limitations instead of filling context with unused mappings.

Bias Detection

Check every finding against 10 bias categories. Read references/bias-detection.md for full detection signals and mitigation strategies.

State Management

• Journal path: ~/.{gemini|copilot|codex|claude}/research/
• Archive path: ~/.{gemini|copilot|codex|claude}/research/archive/
• Filename convention: {YYYY-MM-DD}-{domain}-{slug}.md
  • {domain}: tech, academic, market, policy, factcheck, compare, survey, track, general
  • {slug}: 3-5 word semantic summary, kebab-case
  • Collision: append -v2, -v3
• Format: YAML frontmatter + markdown body + <!-- STATE --> blocks

Save protocol:

• Quick: save once at end with status: Complete
• Standard/Deep/Exhaustive: save after Wave 1 with status: In Progress, update after each wave, finalize after synthesis

Resume protocol:

1. resume (no args): find status: In Progress journals. One → auto-resume. Multiple → show list.
2. resume N: Nth journal from list output (reverse chronological).
3. resume keyword: search frontmatter query and domain_tags for match.

Use !uv run python scripts/journal-store.py for all journal operations.

State snapshot (appended after each wave save):

<!-- STATE
wave_completed: 2
findings_count: 12
leads_pending: ["url1", "url2"]
gaps: ["topic X needs more sources"]
contradictions: 1
next_action: "Wave 3: cross-validate top 8 findings"
-->

In-Session Commands (Deep/Exhaustive)

Available during active research sessions:

Read references/session-commands.md for full protocols.

Reference File Index

Loading rule: Load ONE reference at a time per the "Read When" column. Do not preload.

Stop Hooks

Research-mode stop verification is mandatory when runtime hooks are active. research_hook.py research-stop-verifier delegates to verify.py stop, which checks that tracked files under skills/research/ stayed clean in git during the session. Source-file writes are blocked separately by research-readonly-write-guard. If stop verification fails, report the exact reason and do not claim the run is complete.

Validation Contract

Run from the repository root before declaring changes complete:

(cd skills/research && uv run python scripts/check.py)
uv run pytest tests/test_wagents_hook.py -q -k "readonly_guard or stop_verifier or shell_write_guard"

Completion criteria:

1. scripts/check.py exits 0 after running skill validation, eval validation, package dry-run, and repo audit checks available in the current checkout.
2. The bundled validator reports valid skill metadata and eval manifests.
3. The bundled packaging dry-run reports portable: true.
4. Research hook smoke tests pass for readonly guard and stop verifier behavior.
5. Portable package checks remain free of absolute paths and repo control-plane CLI requirements.

Critical Rules

1. No claim >= 0.7 unless supported by 2+ independent sources — single-source claims cap at 0.6
2. Never fabricate citations — if URL, author, title, or date cannot be verified, use vague attribution ("a study in this tradition") rather than inventing specifics
3. Always surface contradictions explicitly — never silently resolve disagreements; present both sides with evidence
4. Always produce triage scoring before substantial research — user must see and can override complexity tier; wait only when the Plan Gate says approval or clarification is required
5. Save journal after every wave in Deep/Exhaustive mode — enables resume after interruption
6. Never skip Wave 3 (cross-validation and source-support audit) for Standard/Deep/Exhaustive tiers — this is the anti-hallucination mechanism
7. Multi-engine search is mandatory for fact-checking when available — use minimum 3 different search tools (e.g., brave-search + duckduckgo-search + exa); if fewer tools are available, enter degraded mode and cap confidence
8. Apply the Accounting Rule after every parallel dispatch — N dispatched = N accounted for before proceeding to next wave
9. Distinguish facts from interpretations in all output — factual claims carry evidence; interpretive claims are explicitly labeled as analysis
10. Flag all LLM-prior findings — claims matching common training data but lacking fresh evidence must be flagged with bias marker
11. Max confidence 0.4 in degraded mode — when all research tools are unavailable, report all findings as "unverified — based on training knowledge"
12. Load ONE reference file at a time — do not preload all references into context
13. Track mode must load prior journal before searching — avoid re-researching what is already known
14. The synthesis is not a summary — it must integrate findings into novel analysis, identify patterns across sources, and surface emergent insights not present in any single source
15. PreToolUse write guard is non-negotiable — research_hook.py research-readonly-write-guard blocks source-file writes; journals stay under ~/.{gemini|copilot|codex|claude}/research/
16. Stop hook must pass — research_hook.py research-stop-verifier delegates to verify.py stop and confirms tracked skills/research/ files stayed git-clean
17. Normalize legacy findings before synthesis — top-level source_url, source_tool, and confidence_raw must be converted into the canonical evidence[] + confidence shape
18. A citation is not proof by itself — cited source text must support the exact statement; unsupported or merely topical citations lower confidence and appear in the source-support audit