deep-research

Deep Research

Deterministic research pipeline that produces reproducible, schema-validated output. Same input + same state = same output.

Triggers

Activate when the user asks for rigorous multi-source research or uses any of these commands:

• /deep-research [topic]
• /deepresearch [topic]
• /dpr [topic]
• /dp [topic]
• /dr [topic]

Quick Start

S="{baseDir}/scripts"
B="{baseDir}"

# Full deterministic run (after claims + evidence are collected):
python3 $S/run_deep_research.py \
  --topic "Does caffeine improve focus?" \
  --topic-summary "Common belief that caffeine enhances concentration." \
  --claims-file /tmp/dr-claims.json \
  --evidence-file /tmp/dr-evidence.json \
  --policy $B/policy.json \
  --schema $B/output-schema.json \
  --state $B/state.json \
  --output-json /tmp/dr-output.json \
  --output-md /tmp/dr-output.md

Exit codes: 0 success, 1 validation/policy error, 2 partial retrieval, 3 no-evidence fallback.

Workflow

Phase 1: General Research (Agent-Driven)

Search the web to understand the topic. Identify up to 5 key claims to fact-check.

Write claims to a JSON file using this exact schema:

[
  {
    "claim_text": "Caffeine (100-300mg) improves sustained attention",
    "evidence_required": "RCTs or meta-analyses on caffeine and attention",
    "confidence_target": 0.7
  }
]

Required fields per claim: claim_text, evidence_required, confidence_target.

Phase 2: Scientific Fact-Check (Agent-Driven)

For each claim, search source databases in tier order:

Tier	Sources	Flag
peer_reviewed	PubMed, Google Scholar	✅
preprint	arXiv, bioRxiv, medRxiv	📝
community	Reddit, StackExchange, forums	🗨️
social	X/Twitter	🐦

Evidence budget per claim: 2 peer-reviewed + 1 fallback (max 5 total).

Write evidence to a JSON file:

[
  {
    "claim_id": "C001",
    "sources": [
      {
        "title": "Effects of caffeine on cognitive performance",
        "authors": "Smith et al.",
        "year": 2020,
        "tier": "peer_reviewed",
        "url": "https://pubmed.ncbi.nlm.nih.gov/12345678",
        "citation": "Smith et al., \"Effects of caffeine on cognitive performance\", J. Neuroscience, 2020. https://pubmed.ncbi.nlm.nih.gov/12345678",
        "supports_claim": true,
        "relevance_note": "RCT showing improved reaction time at 200mg dose",
        "retrieved_at": "2026-02-26T10:00:00+00:00"
      }
    ]
  }
]