# The agent layer

The skill, the three rubrics, and the 0–3 screening scale the whole pipeline turns on.

Three stages belong to the model: `plan`, `screen` and `rerank`. Each is performed
under a rubric that ships as plain Markdown with the skill, in
`skills/research-scan/references/`.

Shipping the rubrics as readable files rather than as prompts inside a package is
deliberate. You can read what the screener was told, disagree with it, and change
it — and because scores land in a file, you can see what your change did.

## The skill

The skill is the instruction set the hosting agent follows. It opens by stating
the division of labour:

> You produce a verified evidence scan for a research question, topic or project.
> You do the reasoning; the `research-scan` CLI does retrieval, expansion,
> shortlisting, verification and rendering. Never cite a paper that is not in the
> run's files; never edit paper metadata from memory.

Those last two clauses are the whole discipline in one sentence. Everything the
agent says about a paper has to be traceable to a file the CLI wrote.

The skill declares which tools it needs — `Bash(research-scan *)`, `Read`,
`Write`, `Edit`, `Glob`, `Grep`, and the four MCP tools — and runs in a forked
context, which has consequences for
[headless invocation](/concepts/research-scan-as-agent-primitive/#running-it-unattended).

## Planning

The plan rubric turns a brief into `queries.json`: 6–8 queries and 3–6
sub-criteria.

Its headline rule is about query shape:

> **The single rule that matters most: 2–4 core terms naming one concept.**

Four query types are mandatory, and the reason is that they force a plan to argue
with itself rather than only confirm the brief:

| Type | Why it is mandatory |
|---|---|
| `direct` | The question as asked. |
| `terminology` | The other vocabulary the field uses for the same idea. |
| `contradictory` | Aimed at the brief's own premise. |
| `review` | Surveys and syntheses. |

Optional types — `mechanism`, `method`, `adjacent`, `emerging` — are added when the
brief calls for them. The sub-criteria the plan derives depend on the purpose:
`build`, `research` and `orient` each pull a different set of dimensions.

Exclusions from the brief become `must_not` terms, enforced in code at word
boundaries. Known papers become `anchors`: pinned into the pool, exempt from the
filters and the cap, and always used as expansion seeds.

## Screening: the 0–3 scale

Every candidate is scored against the brief's sub-criteria. This is the scale the
whole pipeline turns on.

| Score | Meaning | Test |
|---|---|---|
| **3** | central | Squarely about the brief's decision. You would be surprised if the final list omitted it. |
| **2** | relevant | Satisfies at least one sub-criterion properly. Worth the reranker's time. |
| **1** | tangential | Right vocabulary, wrong question — a nudge study in an unrelated domain, a mechanism paper with no bearing on the decision. |
| **0** | off-topic | Matched a keyword in another sense. Object detection, oncology trials, a paper about *loan* default. |

The rubric is explicit about where the real decision lies:

> The 2 boundary is the one that matters. Everything scoring ≥ 2 becomes an
> expansion seed and reaches the shortlist; everything below is invisible from
> here on. When genuinely torn, ask: *does this paper give evidence on a
> sub-criterion, or does it merely share vocabulary with one?* Evidence → 2.

Four more screening rules do a lot of work:

**Do not reward citation counts or venue prestige.** The screener is not shown
them, deliberately. A 2026 paper and a 2015 paper with 4,000 citations arrive
looking the same.

**Do reward contradiction.** A paper that argues against the brief's premise is
evidence, not noise.

**Judge on the abstract you were given.** Abstracts are truncated to 600
characters. The screener scores what is in front of it rather than what it
remembers about the paper.

**Watch for the false friend.** `default` means loan default, `inertia` means grid
inertia, `anchoring` means seabed anchors. Most 0s are this.

Reasons are capped at twenty words, and every 2 or 3 must name which criterion it
hit.

### Batch families

Screening runs in batches, and the filename tells you where a candidate came from:

| Prefix | Origin |
|---|---|
| `01`, `02`, … | Retrieved candidates |
| `x01`, … | Citation-graph expansion |
| `r01`, … | Gap round, retrieved |
| `xr01`, … | Gap round, expansion |

## Reranking

The rerank rubric scores the shortlist per sub-criterion and overall, and writes
the argument that ships with each paper.

**`overall` is holistic, not an average.** A paper can hit two criteria weakly and
still not matter; a paper can hit one criterion decisively and be the most
important item on the list.

**The off-domain cap.** A paper from another domain caps at `overall` 2 unless
`relevance_reason` names an explicit method transfer. The rubric puts it plainly:

> If you cannot name what transfers, it does not transfer.

**`relation`** records how the paper stands to the brief — `design-changing`,
`plan-influencing`, `closely-related`, `contradicting` or `foundational`. This is
orthogonal to how the paper was discovered.

**`evidence_level`** records what kind of evidence it is, from `systematic-review`
and `meta-analysis` down through `observational`, `computational` and
`qualitative`.

Each ranked entry also carries `key_finding`, `why_it_matters`, at least one
limitation, and the `review` / `contradicts` / `methods_paper` flags that the
[selection guarantees](/getting-started/understanding-results/#the-contradicting-reserve)
read.

## What the agent may not do

The rubrics are as clear about the prohibitions as the instructions. No hand-tuned
weight vectors — the rubric scores and code selects. No repairing metadata from
memory. No writing a gap query aimed at a paper you already know is missing. No
building a golden set out of a run's own output.

Each of those would move judgement somewhere it cannot be audited.