The agent layer

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.

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 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.