Paper Navigator

Paper Navigator

Find and read academic papers. Route by intent, judge by relevance.

        User
         │
         ▼
   ┌── Router ──┐
   │            │
   ▼            ▼
 POINT      LIST/ITERATIVE
(1 paper)   (Probe + up to 3 paper rounds:
             R2 breadth / R3 deepen / R4 close)

The agent does relevance judgment — no LLM-as-judge is called, no numeric scoring. You author the rubric, you triage each paper, you rank by relevance.

Setup

Script paths in this document are relative to this skill's directory. Run via python scripts/<name>.py.

Dependencies: pip install deepxiv-sdk httpx (also listed in requirements.txt at the skill root). Install into the environment the user is working in.

arXiv access (arxiv_monitor, scholar_search fallback) uses the DeepXiv SDK: pip install deepxiv-sdk, then deepxiv token once to provision a free API token (saved to ~/.env). The skill reads the token from DEEPXIV_API_TOKEN/DEEPXIV_TOKEN in the environment, or from ./.env / ~/.env.

Full env-var list: references/env-vars.md.

Five Red Lines (always)

1. Track history. Don't re-run a query you already ran. Empty result → change angle, not synonyms.
2. Search a gap, not a vibe. Every query maps to one missing piece of information. No stacked-keyword bags.
3. One query = one concept. Split comparisons (A vs B), multi-property asks, and multi-year spans into separate calls.
4. Never hallucinate. Every fact (title, author, year, citation count, content) comes from a tool result.
5. Quote-or-zero. When you claim a paper meets a criterion, quote a ≤80-char span from its abstract / tldr / snippet. No quote → do not claim the paper meets that criterion. (This guards against hallucination; it does not drive a numeric score.)

Router

Default to LIST when unsure. Don't add survey / review to LIST queries — it down-ranks the canonical research papers the user wants.

Output format follows the caller: the Output column above is the structured form (skill callers). Direct user calls default to Narrative — see Step 6 "Output mode".

Ambiguous query (project nickname, codename, single capitalized word with zero hits) → run scholar_search exact + web/GitHub search first to resolve identifiers, then re-route.

POINT branch (known paper)

Paper Card:

📄 **<Title>**
Authors: <First Author> et al. | Year: <Y> | Venue: <V>
Citations: <N> | ID: <ArXiv:xxxx.xxxxx> | DOI: <...>
TLDR: <one sentence>

Stop here. Do not chain to citation expansion unless asked.

LIST / ITERATIVE branch — 6 steps

Step 1: Parse intent

State in one sentence: the research object (specific technique / concept) and the constraints (domain, task, recency, exclusions). Confirm the router branch. When the user gives only a bare noun (concept / model / algorithm / benchmark name) with no direction, default intent is "trace the lineage" — foundations, evolution, current state — not applications or a generic survey.

Step 2: Author the RUBRIC (via think_tool)

Emit a structured block before any search. It persists across rounds and every later step references it.

RUBRIC for "<user query verbatim>"
Branch: LIST | ITERATIVE
Criteria (2–4, atomic; mark each [core] or [secondary]):
  C1 [core]     <what the paper MUST do/be — one sentence>
  C2 [core]     <...>
  C3 [secondary] <...>
Named entities to preserve verbatim: [<ent1>, <ent2>, ...]
Angle tags (3–5 sub-topic axes): [<tag1>, <tag2>, <tag3>]
Recency signal: [none | recency cue — defined in Step 3]
Disqualifiers: [<auto-reject if abstract shows this>]

Rules:

• Criteria atomic (one condition each), non-redundant. Mark each [core] (must-have) or [secondary] (nice-to-have) — this guides relevance ranking, no weights, no math.
• Named entities = proper-noun / technical-term anchors from the user's query. Every entity appears verbatim in ≥1 query across Probe + R2.
• Angle tags = sub-topic axes (method, task, dataset, evaluation, domain, …). No two queries in the same round share a tag.
• Recency signal = whether the user query carries a recency cue (see Step 3 recency trigger). Drives --year-min and the Step 6 recency tie-break.
• Disqualifiers = "specifically X, not Y" exclusions. Tripping a disqualifier → Irrelevant.

For ITERATIVE, criteria can be lighter (e.g. covers topic + is canonical); disqualifiers may be empty.

Step 3: Search — Probe then Multi-round (Breadth → Deepen → Close)

Probe first to grasp the user's need comprehensively, then run up to 3 paper rounds (R2 breadth / R3 deepen / R4 close). Decide round-by-round whether more rounds are needed (Step 5 gate) — do NOT fix a round count. There is no R5; the cap is 3 paper rounds.

Probe (prerequisite — NOT counted in the 3 rounds, 2 parallel queries): establish a comprehensive understanding of the need and lift named entities / angle gaps.

• Q-broad — canonical phrasing of the topic (angle: general)
• Q-narrow — a specific mechanism / sub-question / method (angle: tagged)

python scripts/scholar_search.py --query "<Q-broad>"  --limit 15 --sort-by relevance --output /tmp/pool.jsonl --append
python scripts/scholar_search.py --query "<Q-narrow>" --limit 15 --sort-by relevance --output /tmp/pool.jsonl --append

--output --append auto-dedupes by paperId across rounds (built into the script), so a paper found by two queries is written once. Read /tmp/pool.jsonl to inspect (Step 4 triage). From Probe titles + tldrs, lift:

• recurring named entities (algorithm / benchmark / dataset / model names),
• angle gaps (Step-2 tags not seen),
• vocabulary from adjacent communities.

R2 — Breadth (default — skipped only via the Step 5 early exit; 2–3 parallel queries). Broad academic queries on the core object + canonical terms lifted from Probe. The main axis is the user's core object + canonical mapping; Probe only supplies high-confidence supplements.

R3 — Targeted deepening (optional, when Step 5 gate says CONTINUE, 2–3 parallel queries). Driven by the gap→strategy map below — fill the specific gap Step 4 triage exposed.

R4 — Closing (optional, 2–3 parallel queries). Fill whatever key gap remains after R3: a missing representative work, a strong baseline, a counter-example, or an uncovered sub-direction.

Gap→strategy map (R3/R4 are driven by the Step-4 triage gap, not vibes):

Per-query rules:

• 3–6 words preferred (English academic terms); <3 over-recalls, >6 dilutes ranking.
• Use academic terms (mechanism, benchmark); no how it works phrasing.
• Do NOT add survey / review / tutorial terms — they bias results toward review papers and crowd out the research papers the user wants. Only use them when the user explicitly asks for a survey/review.
• Bare entity names; no paper / pdf / arxiv / original.
• Split comparisons / multi-property; if short of 2–3 queries, fill with upper-topic or representative method.
• Time intent goes into --year-min/max params, never year words in the query.
• Forbidden: "…", (..), OR, AND, |, site:, filetype:.
• No two queries in one round may share >60% of content tokens (after stop-words).

Recency trigger (query layer). When the user query contains a recency signal (最新 / 近年 / 近期 / 近两年 / 前沿 / SOTA / latest / recent / state-of-the-art), set --year-min to last 2 years from R2 onward — Jan 1 of the year before the current system year (e.g. system date 2026-08 → --year-min 2025). Do not extend to 3–4 years.

Without S2_API_KEY: swap scholar_search for arxiv_monitor --keywords "<variant>" --match-mode flexible --days 3650.

Citation expansion (ITERATIVE, or LIST after ≥3 All-core/Partial seeds):

python scripts/citation_traverse.py --paper-id <SEED> --direction co-citation --limit 15 --output /tmp/pool.jsonl --append
python scripts/citation_traverse.py --paper-id <SEED> --direction forward --limit 20 --min-citations 20 --year-min 2022 --output /tmp/pool.jsonl --append
python scripts/recommend.py --positive <SEED1>,<SEED2> --limit 15 --output /tmp/pool.jsonl --append

Step 4: Triage — All-core / Partial / Irrelevant

After every round, classify each new paper and stamp a per-criterion mask (✓ / ~ / ✗) over the RUBRIC — no numeric scoring. The mask is what makes conjunctive queries ("papers satisfying A and B") terminate correctly: only a paper with ✓ on every [core] criterion is All-core. Emit a think_tool block:

TRIAGE round=<n>  query="<q>"
  All-core   (k): <paperId> "<title-≤60>" Y=<year> · [C1✓ C2✓ (C3~)]   every [core] ✓
                 C1: "<≤80-char quote>"
                 C2: "<≤80-char quote>"
  Partial    (k): <paperId> "<title>" Y=<year> · [C1✓ C2✗]              some [core] ✓
                 C1: "<≤80-char quote>"
  Irrelevant (k): <paperId> "<title>"                                   no [core] ✓, or trips disqualifier — drop

✓ = abstract/tldr clearly supports. ~ = partial / inferable. ✗ = no support or contradicts. [secondary] criteria don't set the tier but still get a mask symbol.

Rules:

1. Dedup across rounds by paperId first, then normalised title. Keep the stronger mask.
2. Disqualifier check beats all other matches → Irrelevant.
3. Re-diagnose gaps: note any [core] criterion with 0 ✓ across All-core+Partial, and any angle tag with 0 All-core/Partial → that's the next refine target (feeds the Step 3 gap→strategy map).
4. No fabrication: missing abstract → stamp ~, do not infer from training data.

The per-criterion quotes collected here are exactly what the Step 6 Rank-1 bar and the structured LIST template cite — do not skip them.

Snippet upgrade for borderline papers (abstract silent on a [core] criterion): batch-fetch real body text:

python scripts/snippet_search.py --query "<criterion phrase>" \
  --paper-ids "CorpusId:1,CorpusId:2,..." --limit 50

Step 5: Saturation Gate

After Probe and each round, decide CONTINUE vs STOP by whether key gaps remain — not by counting papers.

Early exit after Probe (single-recommendation / conjunctive queries only, K=1–2): for "is there a paper that …?", "recommend a paper", "what's the canonical X", or conjunctive "papers satisfying A and B" queries, if an All-core paper already covers every [core] criterion, STOP without running further rounds. This preserves the fast path where one probe hit settles a POINT-like query (≈2 queries), which matters under keyless S2 rate limits. For broader question shapes ("find papers about …" K=3–5, or 30+-paper ITERATIVE), do not use this early exit — apply the full STOP conditions below.

STOP when ALL hold:

• ≥1 All-core paper exists — a single paper with ✓ on every [core] criterion. This is required so conjunctive queries like "papers satisfying A and B" can't pass on two different papers that each cover only one side, AND
• every angle tag has ≥1 All-core/Partial paper, AND
• no key claim rests on a single source,
• OR further rounds stop surfacing anything new (empty recall / all duplicates).

CONTINUE to the next round (R3 / R4) otherwise, driven by the gap→strategy map:

• 0 All-core papers → fill the [core] criterion still ✗.
• An angle tag has 0 All-core/Partial → open that angle.
• A key claim rests on a single source → multi-source corroboration.

Re-decompose (rubric is wrong) if R2 returns 0 All-core AND 0 Partial across the board: report the strongest Partial candidate(s) + ask the user to relax a criterion.

Round caps: LIST and ITERATIVE up to 3 paper rounds (R2/R3/R4). POINT is a single fetch (no multi-round). If still not saturated at the cap, go to Step 6 and report which criteria / angle tags were not covered.

The gate is mechanical about gaps — do not skip rounds because "the results look right"; do not run extra rounds once the STOP conditions hold. The single-All-core-suffices shortcut applies only to the K=1–2 early exit above, not to broader queries.