research

Research Orchestrator

Accepts a freeform research request, plans scope, manages a 7-phase claim-based pipeline with 4 human checkpoint gates, and produces a polished, citation-rich research document. Every claim is traceable to its source, every gap is detected and addressed, and every run is reproducible and auditable.

The orchestrator coordinates collection, claim extraction, graph relationship enrichment, section brief synthesis, report composition, and optional publishing. output/report.md is the canonical final report; HTML, PDF, and QMD are publishing products rendered from it.

Claim Pipeline Contract

New runs use manifest.pipeline_contract_version = "claim_pipeline_v1" and these phases:

planning
→ collection
→ claim_extraction
→ graph_relationships
→ section_brief_synthesis
→ formatting
→ publishing

synthesis/claim_bank.json is the canonical research state. synthesis/raw_research.md is deprecated; if a prose diagnostic is needed, write synthesis/research_notes.md and keep it out of the main handoff.

A global file is tiny only when it is under 20KB or under 300 lines. Downstream agents must not read full claim_bank.json, full inventory.json, full graph files, or all section briefs unless the file qualifies as tiny. Otherwise they consume per-section slices.

---

Dependency install policy

The research pipeline must NEVER auto-install or auto-download these runtime dependencies:

• crawl4ai (and its Playwright/browser runtime)
• playwright / Playwright browsers
• docling

If any of these are missing when the pipeline needs them, the skill/agent MUST:

1. Detect the missing dependency.
2. Emit a clear message naming the missing tool and the install command the user can run themselves (e.g., pipx install crawl4ai, pipx install docling, playwright install chromium).
3. Stop the run — halt the phase with a non-zero exit. Do NOT proceed with a fallback collection mode.

Never execute pip install, pipx install, npm install, playwright install, crawl4ai-setup, crawl4ai-doctor --install, or any equivalent install command for these tools from within the pipeline.