research-scan

# research-scan

Research Scan finds and verifies the papers that matter for a research question, project, or decision. Starting from a brief or a single question, it runs a structured evidence pipeline that retrieves literature, expands through citation graphs, screens candidates, and verifies results before producing evidence objects.

The work is split in two, deliberately.

**The CLI is deterministic and model-free.** It retrieves across OpenAlex, Semantic Scholar and
arXiv, walks the citation graph, dedups, counts coverage per criterion, shortlists, verifies every
DOI against the live record, applies the selection rules and renders the result. It contains no LLM
SDK and makes no judgement about a paper.

**The agent supplies the cognition.** Planning the queries, scoring each candidate 0–3, writing gap
queries when coverage is thin, and reranking the shortlist are all model decisions. The skill
packages the rubrics they are made against, as plain Markdown in `skills/research-scan/references/`;
whatever agent hosts it executes them.

Files are the interface between the two halves: the filesystem is the protocol boundary between
reasoning and execution, not a storage detail. That is what lets Claude Code, Codex, Cursor or a
plain Python loop drive the same chain over the same artifacts.

```
brief ─▶ [plan queries] ─▶ retrieve ─▶ [screen 0–3] ─▶ expand ─▶ [screen] ─▶ coverage
      ─▶ [gap round, if coverage is thin] ─▶ shortlist ─▶ [rerank] ─▶ verify ─▶ emit
```

Bracketed steps are the agent's; the rest are CLI stages.

Two things bound the result. A **purpose** — `build`, `research` or `orient` — decides what a paper
has to do to earn a slot. A **profile** — `quick`, `standard` or `deep` — decides how much the scan
costs. Both are described under [How it works](#how-it-works).

Output is a run directory of validated JSON plus a Markdown brief you can hand to a human, in which
every paper's DOI, title, year and first author were checked against the live record.

## Install

Python ≥ 3.11 and [uv](https://docs.astral.sh/uv/).

```bash
uvx research-scan doctor          # run any command without installing
uv tool install research-scan     # or put it on PATH permanently
```

## Configure

`configure` asks for each credential, shows what is already set, writes
`~/.config/research-scan/.env` with mode `0600` inside a `0700` directory, and finishes by running
`doctor`.

```bash
research-scan configure          # `setup` is an alias for the same command
```

Keys are read without echo. Re-running is safe: every variable shows its current value masked to the
last four characters, Enter keeps it, typing replaces it. Anything already in the file that
`configure` does not ask about — comments included — is left exactly as it was. If stdin is not a
terminal it prints the file to write and exits 2 rather than hanging, which is the behaviour you
want in a Dockerfile or a provisioning script.

| Variable | Needed for |
|---|---|
| `OPENALEX_API_KEY` | OpenAlex, the primary source. **Required**; `doctor` exits 3 without it. |
| `OPENALEX_MAILTO` | Strongly recommended. Raises OpenAlex to 5 req/s and joins the Crossref polite pool. |
| `S2_API_KEY` | Recommended. Semantic Scholar search and citation-graph expansion work without it, throttled to roughly a third of the rate; `doctor` warns. |
| `NCBI_API_KEY` | Optional. PubMed only: 10 req/s instead of 3. |

To write the file by hand instead, `.env.example` in the repo is the template. Process environment
beats `~/.config/research-scan/.env`, which beats a repo-local `./.env`.

## Check it works

`doctor` invokes every source live with the cache bypassed, rather than listing what it thinks is
configured.

```bash
research-scan doctor             # a four-line summary and a verdict
research-scan doctor --verbose   # every check, with timings and paths
research-scan doctor --json      # machine-readable; this is the CI/agent interface
```

```
Research Scan <version>
✓ configuration
✓ OpenAlex   ✓ Semantic Scholar   ✓ Crossref   ✓ arXiv   ✓ PubMed
✓ writable run store
Ready.
```

Exit 0 means go. Exit 3 means a mandatory check failed; see [Troubleshooting](#troubleshooting). The
checks and the exit code are identical in all three output modes — only the presentation differs.

## Your first scan

With the skill installed, ask for a scan in your agent:

```
/research-scan "I am designing a financial education product for young adults. 
Research question: What interventions have the strongest recent evidence for increasing 
long-term savings behavior?

Context:
- I am interested in mechanisms that change real-world behavior, not just 
financial literacy scores.
- Prioritize randomized trials, large field studies, and strong causal evidence.
- Include evidence that challenges the assumption that education alone works.

Find the 10 papers that should shape our product decisions. Explain why each paper matters, what it 
found, and what evidence gaps remain." --profile standard
```

A one-line question works. A brief with context works better, because the planning step maps each section of it onto a specific part of the search plan. The template is
`skills/research-scan/examples/brief.example.md` — a worked `build` brief — and
`brief.research-example.md` is the same template at `Purpose: research`.

```
/research-scan research/my-brief.md --profile standard --top 10
```

| Brief section | What it feeds |
|---|---|
| **`Purpose:` line** | Which sub-criteria the plan derives and what `why_it_matters` must argue. `build`, `research` or `orient`; omit it and the agent infers one. |
| **What this is about** | The `brief_summary` and the domain routing. Say the setting, not just the topic. |
| **What we need to decide or answer** | The sub-criteria every paper is scored against. Name the actual open choices, or the actual questions. |
| **What we already believe (the premise)** | The `contradictory` query. A scan that only confirms the premise is not evidence. |
| **Exclusions** | `queries.json.must_not`, enforced in code at word boundaries — never as NOT-terms in query text. |
| **Known papers or authors** | `anchors`: pinned into the pool, exempt from the filters and the cap, always used as expansion seeds. |

Results land in `research/scans/<YYYY-MM-DD>-<slug>/`. See [Outputs](#outputs).

Full argument list:

```
/research-scan <brief.md | "question"> [--profile quick|standard|deep] [--top N] [--foundational N]
                                       [--from YYYY-MM] [--to YYYY-MM] [--slug name]
                                       [--domain behavioral|cs|biomed|general]
                                       [--max-candidates N] [--per-query N]
```

## Connect your agent

Two front doors to the same pipeline. The skill is where the rubrics live, so it is the one that
carries the screening and reranking cognition; the MCP server exposes the same four decision points
as tools for any client that speaks MCP.

### Claude Code — the skill

Any one of these; all three point at the same `skills/research-scan/`.

```bash
# 1. symlink a clone — edits to the rubrics take effect immediately
ln -s "$PWD/skills/research-scan" ~/.claude/skills/research-scan

# 2. load the repo as a plugin, per invocation (it carries .claude-plugin/plugin.json)
claude --plugin-dir /path/to/research-scan

# 3. skills CLI
npx skills add Synectic-Research/research-scan
```

### Claude Code — the plugin

The plugin installs the skill and configures the `uvx` MCP server in one step; the `.mcp.json` route
below stays the path for non-plugin clients such as Claude Desktop and Cursor.

```bash
/plugin marketplace add Synectic-Research/research-scan
/plugin install research-scan@synectic
```

### Any MCP client — stdio

`research-scan mcp` speaks MCP on stdin/stdout and nothing else. It reads no token and needs none:
the process is trusted because your client launched it. Nothing extra to install — the server
ships with the package.

```json
{
  "mcpServers": {
    "research-scan": {
      "command": "uvx",
      "args": ["research-scan", "mcp"]
    }
  }
}
```

| Client | Where that goes |
|---|---|
| Claude Code | `.mcp.json` in the project root |
| Claude Desktop | `claude_desktop_config.json` |
| Cursor | `.cursor/mcp.json` |

Four tools, one per model decision the pipeline needs: `scan_start` (you supply the query plan),
`scan_continue` (screening scores, gap queries, or a page of rerank entries), `scan_verify` and
`scan_result`. They are not a chat endpoint over the pipeline: each is a decision point where a
judgement is needed, and the client's model supplies exactly the cognition the skill would — same
stage order, same artifacts. The adapter drives the CLI as a subprocess and reads its exit codes.
Run `research-scan mcp --help` for the other transport.

## How it works

Each stage is idempotent and re-runnable: change `queries.json` or pass a flag and re-run from the
stage it affects. The CLI owns `candidates.json`, `shortlist.json`, `manifest.json` and
`evidence.*`; the agent owns `queries.json`, `screen.json` and `ranked.json`. Neither edits the
other's files.

### Purpose

Declared on the brief's `Purpose:` line, or inferred. It decides which sub-criteria the plan derives,
what screening counts as relevant, and what `why_it_matters` has to argue.

| Purpose | A paper earns its place by | Example |
|---|---|---|
| `build` | moving a design or plan decision | "What should we know before we design the enrolment flow?" |
| `research` | changing what we believe, what we would test, or how we would measure it | "What is the strongest recent evidence that default enrolment affects how much people save?" |
| `orient` | being something a newcomer must know, recent first | "I am new to mechanistic interpretability — what must I read, recent first?" |

### Profiles

One flag sets how much the scan costs. `--profile` belongs to `init` and is recorded in the manifest;
an explicit flag still overrides it — `--per-query 60`