Understanding your results
What a run directory contains, what an EvidencePacket carries, and how to read the verification record.
Every scan produces a directory, not a message. That is the point: the output is a set of files any tool can read, re-check and re-run.
Results land in research/scans/<YYYY-MM-DD>-<slug>/.
The deliverable
| File | What it is |
|---|---|
evidence.json | The deliverable: one EvidencePacket per paper — metadata, rerank scores, key finding, why it matters, limitations, and the verification record. |
evidence.md | The same list rendered for a human. |
evidence.bib | BibTeX for the emitted papers. Suppress with --no-bib. |
In evidence.md, foundational classics render after the current work, with
ranks running straight through, so a 2004 paper reads as context rather than as
the answer.
The audit trail
| File | What it is |
|---|---|
manifest.json | Every drop — retracted, excluded, type-filtered, pool-capped — and every source that failed after retries. Nothing is capped silently. |
coverage.json | Per sub-criterion, how many kept papers cover it, split by query type and source, plus per-query yield and per-seed expansion precision. One snapshot per round, so what the gap round recovered is a delta. |
queries.json, candidates.json, screen.json, expanded.json, shortlist.json, ranked.json | The intermediate stages, all schema-validated. |
retrieval.log.jsonl, expansion.log.jsonl, verify.log.jsonl | Per-stage structured logs. |
Ownership is split and never crossed: the CLI owns candidates.json,
shortlist.json, manifest.json and evidence.*; the agent owns queries.json,
screen.json and ranked.json.
What an EvidencePacket carries
An EvidencePacket is a candidate, plus its rerank, plus its verification, plus
why it was selected — the shippable unit. Beyond the usual bibliographic fields
(title, authors, year, venue, DOI and the other identifiers), each one carries:
| Field | What it holds |
|---|---|
overall | A holistic 0–3 score. Not an average of the per-criterion scores. |
criteria | A 0–3 score per sub-criterion from the brief. |
relation | How the paper stands to the brief. See below. |
evidence_level | systematic-review, meta-analysis, rct, prospective, observational, experimental, computational, qualitative, other. |
key_finding | What the paper found. |
why_it_matters | The argument for this paper, in the terms the brief’s purpose demands. |
limitations | At least one. A packet with no stated limitation does not validate. |
flags | review, contradicts, methods_paper. |
verification | The verification record. |
rank, selection_reason | Where it landed and why. |
Print the full contract at any time:
research-scan schema --name EvidencePacketresearch-scan schema --md # every model, as Markdownrelation — how a paper stands to the brief
| Value | Meaning |
|---|---|
design-changing | Changes a design decision. |
plan-influencing | Changes a plan. |
closely-related | Directly on the question. |
contradicting | Argues against the brief’s premise. |
foundational | A classic a newcomer must know; usually outside the date window. |
This is orthogonal to how the paper was found. Discovery origin is recorded
separately, as query, references, citations, recommendations or anchor.
selection_reason — why it made the list
score, foundational, review, contradicting, diversity or backfill.
Most papers arrive by score. The others are the guarantees below.
The contradicting reserve
A scan that only confirms the brief’s premise is not evidence. So two slots are guaranteed rather than earned by ordering.
One review slot, with the higher floor — the paper must score overall 3 or be
closely-related, because an off-topic review in a guaranteed slot is worse than
no review at all.
One counter-result slot by default, controlled by --contradicting. Set it to
0 to disable; it is capped at half of --top either way.
Together the guarantees may take at most half the main slots. Everything else is ordering.
Reading the verification record
Every ranked paper’s DOI, title, year and first author are checked against the live record before it ships.
A paper whose DOI did not resolve, or whose metadata disagreed, is flagged, not
silently repaired. It ships with a populated mismatches[] and an
[UNVERIFIED — check manually] marker in the Markdown. Only retraction removes a
paper.
That is a deliberate choice: repairing metadata from a model’s memory is exactly the failure this tool exists to prevent. See Verification for how the check runs and what each mismatch code means.
Last updated Aug 21, 2026