Documentation
README
Deep-Research β Source-Validated Literature Review Engine
Answer a hard question properly and hand back a written, formatted, integrity-
checked literature review β not just notes. Scope β design β discover β screen
by journal ranking β validate sources β extract & verify evidence β synthesize β
stress-test β write β review-loop β final report. Original work; architecture
informed by open community food-deep-research skills (see the repo README
Acknowledgements). Usable standalone, or as the deep-dive engine called by
food-research.
Modes
- quick brief β scope β discover β screen (Tier 1) β light synthesis β short sourced answer. Skips the full validation/compile/review loop.
- full β the default: the complete 12-subagent pipeline below with the iterate-to-saturation and compileβreview loops, ending in a finished review.
Subagent team (dispatch via the Agent tool)
| # | Subagent | Job |
|---|---|---|
| 1 | research_scope |
Comprehensive scope brief: background, problem, significance, central + sub-questions, concepts, boundaries, success criteria. |
| 2 | research_architect |
Methodology blueprint: review type, search strategy, inclusion criteria, analytical framework, reporting standard, stopping criteria. |
| 3 | investigator |
Pass 1 discover candidate sources; Pass 2 extract evidence from validated sources only (parallel per sub-question). |
| 4 | source_screener |
Prioritize candidates by journal ranking (Tier 1 Q1/Q2 + Nature/Science/Cell + other-discipline Q1/Q2; Tier 2 Q3; avoid Tier 4). |
| 5 | source_verifier |
Validate each prioritized source (existence/DOI, venue legitimacy, retraction, predatory, methodology, COI) β Source Quality Matrix. |
| 6 | bibliography |
Deduplicate + format references (APA 7.0 default, or target-journal style via journal-selector); build the citation map + .bib/.ris. |
| 7 | claim_verifier |
Verify each load-bearing claim against its validated source; classify fact/hypothesis/contested/speculation. |
| 8 | synthesizer |
Evidence matrix, thematic synthesis, conflict reconciliation, evidence grading, coverage advisory, gap agenda, narrative arc. |
| 9 | critic |
Devil's advocate on the synthesis; loop back to investigate if gaps. |
| 10 | compiler |
Write & format the literature-review draft (APA 7.0 / target journal); cite by key only; no fabrication. |
| 11 | editor |
Editorial review of the draft (5 weighted dimensions, verdict + prioritized feedback). |
| 12 | ethics_reviewer |
Integrity/ethics review of the draft (citation integrity, faithful representation, bias, COI, disclosure). |
Workflow
flowchart TD
A[research_scope<br/>scope brief] --> B[research_architect<br/>methodology blueprint]
B --> C[investigator Pass 1<br/>discover candidate sources]
C --> D[source_screener<br/>journal-ranking tiers]
D --> E[source_verifier<br/>validate β Source Quality Matrix]
E --> F[bibliography<br/>dedupe + format + citation map]
E --> G[investigator Pass 2<br/>extract evidence from validated sources]
G --> H[claim_verifier<br/>verify claims vs validated sources]
H --> I[synthesizer<br/>matrix, themes, conflicts, grading, gaps]
I --> J[critic<br/>stress-test synthesis]
J -- gaps --> C
J -- sound --> K[compiler<br/>write + format review<br/>APA 7.0 / target journal]
F --> K
K --> L[editor + ethics_reviewer<br/>editorial + integrity review]
L -- minor/major revision --> K
L -- accept --> M[Final literature review]
Two loops: (1) evidence loop β critic sends gaps back to investigator
(cap ~2β3); (2) writing loop β editor/ethics_reviewer send revisions back
to compiler until Accept (cap ~2β3), then deliver.
Source discipline (non-negotiable)
- Investigation and claim-checking operate only on validated sources β those that passed
source_screener(ranking) andsource_verifier(validity). Retracted/unresolvable sources are excluded and logged. - Journal ranking favors Tier 1 (Q1/Q2 food-science & nutrition, Nature/Science/Cell families, Q1/Q2 in any other discipline); Tier 2 (Q3) only to fill gaps; Tier 4 avoided.
- Every claim carries a source and locator; inference is labelled as inference.
Formatting β resolve the target journal once
At the start, call journal-selector, which asks which journal the review
targets (they may answer 'generic' β APA 7.0). Ask once: record the
choice and reuse it in bibliography and compiler to format the review to that
journal's structure, limits, and reference style β don't ask again. Reuse a
journal already resolved by food-research/food-pipeline; re-resolve only if the
user asks to switch journals.
Principles
Every claim sourced; fact separated from interpretation; disagreement shown, not
averaged; uncertainty surfaced. Upstream evidence beats parametric knowledge β
mark missing evidence [EVIDENCE GAP], never fabricate.
References (load as needed)
references/reasoning-and-fallacies.mdβsynthesizer/critic: sound argument + fallacies.food-research/references/literature-sources.mdβ databases/APIs forinvestigator.food-research/references/source-quality-hierarchy.mdβ evidence grading forsource_verifier/synthesizer.food-research/references/reporting-guidelines.mdβ EQUATOR/PRISMA/CONSORT/STROBE.food-paper/references/apa7-quickref.mdβ APA 7.0 forbibliography/compiler(default style).food-review/references/ethics-integrity-checklist.mdβ forethics_reviewer.food-paper/references/faithfulness-and-citation.mdβ grounding + four-gate citation check forbibliography,source_verifier,claim_verifier,compiler. Never invent sources/data; runscripts/verify_citations.py.food-paper/references/privacy-and-confidentiality.mdβ privacy scan before delivering the report (no local paths/secrets);scripts/privacy_scan.py.
Handoff
Standalone β deliver the final review. Called by food-research β return the
validated synthesis (or the finished review) to fold into the evidence brief.