ali-demirbas research-intelligence
Overview
Three stages: Planner → Router → Synthesizer. This file stays thin on purpose — sub-skills load only when actually dispatched, so a quick single-source request never pulls in the whole pipeline's token cost. See ../../ARCHITECTURE.md for the 13 locked rules everything below implements; this file doesn't restate them.
Stage 1 — Planner
Invoke research-planner. It decomposes the question into sub-questions, matches each to source skills, sets a search budget, and sets the stopping condition. For anything beyond quick-research, it confirms the drafted scope with the user before dispatch — a full pipeline can touch most of the 8 source skills and take a long time, and that's the cheap point to narrow it. Its output is a user-confirmed plan, written to the run's ledger — not evidence.
Stage 2 — Router
Dispatch the source skills the plan calls for: web-research, github-research, reddit-research, blog-research, news-research, academic-research, official-source-research, social-research. Invoke by name — never inline a source skill's procedure here; each loads only when actually needed for this run.
Each source skill writes evidence.jsonl records with verification_status: pending. When the plan's stopping condition is met (constitution rule 11: every sub-question meets its bar, or 2 consecutive rounds with no new evidence), collection ends for that run.
Then invoke source-verify on the full pending set — mandatory, no run skips this. It resolves every record to verified, rejected, or unreachable before anything downstream touches it.
Before synthesis, run the red-team pass (constitution rule 11): dispatch source skills again, this time with queries designed to refute the run's strongest emerging findings, not to confirm them. Any new evidence this surfaces goes through source-verify the same as anything else.
Stage 3 — Synthesizer
Build findings.jsonl from verified evidence per ../../engine/synthesis-contract.md: fact findings need ≥1 verified evidence id; interpretation/recommendation findings derive from other findings, and a recommendation's closure needs ≥1 verified fact (constitution rule 7). Every sentence traces to an evidence_id or a derived_from finding — no unattributed model claims (constitution rule 2).
Do not assign status by judgment — leave it null and let the validator compute it (constitution rule 3). Run python3 ../../scripts/validate_run.py --strict --write <run_dir> and fix findings until it passes clean; --write persists the computed status back to findings.jsonl so the renderer has real values to read, not null. That is what "done" means here.
--strict is the production setting, not an option: without it, warnings pass silently, and the warnings are where the "did you mean this?" cases live — evidence cited for context that doesn't count toward a bar, a finding sharing evidence with an open contradiction it doesn't list, two records with near-identical quotes filed under different roots. Run without --strict only while iterating.
Render the report with python3 ../../scripts/render_report.py <run_dir> — this is the actual implementation of constitution rule 10 ("the report always renders from findings.jsonl, never hand-written"). It reads findings.jsonl, evidence.jsonl, contradictions.jsonl, gaps.jsonl and run.json, and produces the report per ../../templates/report.md's section rules. Never write the report as free prose instead.
Choosing a workflow
Different research shapes need different Stage-2 depth. See ../../workflows/ for the parameterized versions of this same pipeline: quick-research.md (1 round, light verify), deep-research.md (loop-until-dry + red-team), competitive-research.md, market-research.md, technology-research.md, update-research.md (diffs against a prior run instead of starting fresh).
What never changes regardless of workflow
Every source skill produces evidence only (rule 1). Every record passes through source-verify before it can be cited (rule 6). Status is always validator-computed, never model-assigned (rule 3). The report always renders from findings.jsonl via the actual renderer, never free prose (rule 10). These hold in the 1-round quick workflow exactly as in the deepest one — only the budget, verify depth, and red-team pass scale.