# 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:

```bash
research-scan schema --name EvidencePacket
research-scan schema --md              # every model, as Markdown
```

### `relation` — 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](/architecture/verification/) for how the check runs and what each
mismatch code means.