deepxiv¶
literature-discovery · literature-synthesis
DeepXiv Paper Search & Progressive Reading¶
Search topic or paper ID: $ARGUMENTS
Role & Positioning¶
DeepXiv is the progressive-reading literature source:
| Skill | Best for |
|---|---|
/arxiv |
Direct preprint search and PDF download |
/semantic-scholar |
Published venue metadata, citation counts, DOI links |
/deepxiv |
Layered reading: search → brief → head → section, plus trending and web search |
Use DeepXiv when you want to avoid loading full papers too early.
Constants¶
- DEEPXIV_FETCHER — canonical name
deepxiv_fetch.py, resolved pershared-references/integration-contract.md§2 (Policy D1 — primary + fallback cascade). If unresolved (canonical chain exhausted), fall back to the rawdeepxivCLI (documented per command below). - MAX_RESULTS = 10 — Default number of results to return.
Overrides (append to arguments): -
/deepxiv "agent memory" - max: 5— top 5 results -/deepxiv "2409.05591" - brief— quick paper summary -/deepxiv "2409.05591" - head— metadata + section overview -/deepxiv "2409.05591" - section: Introduction— read one section only -/deepxiv "trending" - days: 14 - max: 10— trending papers -/deepxiv "karpathy" - web— DeepXiv web search -/deepxiv "258001" - sc— Semantic Scholar metadata by ID
Setup¶
DeepXiv is optional. If the CLI is not installed, tell the user:
On first use, deepxiv auto-registers a free token and stores it in ~/.env.
Workflow¶
Step 1: Parse Arguments¶
Parse $ARGUMENTS for:
- Query or ID: a paper topic, arXiv ID, or Semantic Scholar ID
- max: N: overrideMAX_RESULTS- brief: fetch paper brief- head: fetch metadata and section map- section: NAME: fetch one named section- trendingor querytrending: fetch trending papers- days: 7|14|30: trending time window- web: run DeepXiv web search- sc: fetch Semantic Scholar metadata by ID
If the main argument looks like an arXiv ID and no explicit mode is given, default to - brief.
Step 2: Locate the Adapter¶
Resolve $DEEPXIV_FETCHER via the canonical strict-safe chain (see
shared-references/integration-contract.md §2).
Policy D1 cascade: the resolved adapter is preferred; if unresolved
(canonical chain exhausted), fall back to raw deepxiv CLI commands
documented in Step 3.
cd "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" || exit 1
if [ -z "${ARIS_REPO:-}" ] && [ -f .aris/installed-skills.txt ]; then
ARIS_REPO=$(awk -F'\t' '$1=="repo_root"{print $2; exit}' .aris/installed-skills.txt 2>/dev/null) || true
fi
DEEPXIV_FETCHER=".aris/tools/deepxiv_fetch.py"
[ -f "$DEEPXIV_FETCHER" ] || DEEPXIV_FETCHER="tools/deepxiv_fetch.py"
[ -f "$DEEPXIV_FETCHER" ] || { [ -n "${ARIS_REPO:-}" ] && DEEPXIV_FETCHER="$ARIS_REPO/tools/deepxiv_fetch.py"; }
[ -f "$DEEPXIV_FETCHER" ] || DEEPXIV_FETCHER=""
## Smoke test (optional — adapter resolution shown to user). The cascade
## in Step 3 below branches purely on `[ -n "$DEEPXIV_FETCHER" ]`; a
## resolved-but-non-functional adapter is not currently auto-demoted.
if [ -n "$DEEPXIV_FETCHER" ]; then
echo "DeepXiv adapter resolved at: $DEEPXIV_FETCHER" >&2
else
echo "DeepXiv adapter unresolved (canonical chain exhausted); raw deepxiv CLI fallback will be used." >&2
fi
Step 3: Execute the Minimal Command¶
Search papers
Fallback:
Brief summary
Fallback:
Section map
Fallback:
Specific section
Fallback:
Trending
Fallback:
Web search
Fallback:
Semantic Scholar metadata
Fallback:
Step 4: Present Results¶
When searching, present a compact table:
| # | ID | Title | Year | Citations | Notes |
|---|----|-------|------|-----------|-------|
When reading a paper, show:
- title
- arXiv ID
- authors
- venue/date if available
- TLDR or abstract summary
- suggested next step:
brief→head→section
Step 5: Escalate Depth Only When Needed¶
Use this progression:
searchpaper-briefpaper-headpaper-section- full paper only if necessary
Do not jump to full-paper reads when a brief or one section answers the question.
Step 6: Update Research Wiki (if active)¶
Required when research-wiki/ exists in the project; skip silently
otherwise. When the wiki dir exists, resolve $WIKI_SCRIPT per the
canonical chain at
shared-references/wiki-helper-resolution.md
(Variant B — warn-and-skip). Ingest papers that were meaningfully
read (brief / head / section / full) during this invocation — mere
search hits without a depth read do not need ingestion:
if [ -d research-wiki/ ]; then
cd "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" || exit 1
ARIS_REPO="${ARIS_REPO:-$(awk -F'\t' '$1=="repo_root"{print $2; exit}' .aris/installed-skills.txt 2>/dev/null)}"
WIKI_SCRIPT=".aris/tools/research_wiki.py"
[ -f "$WIKI_SCRIPT" ] || WIKI_SCRIPT="tools/research_wiki.py"
[ -f "$WIKI_SCRIPT" ] || { [ -n "${ARIS_REPO:-}" ] && WIKI_SCRIPT="$ARIS_REPO/tools/research_wiki.py"; }
[ -f "$WIKI_SCRIPT" ] || {
echo "WARN: research_wiki.py not found; depth-read summary delivered, wiki ingest skipped. Fix: bash tools/install_aris.sh, export ARIS_REPO, or cp <ARIS-repo>/tools/research_wiki.py tools/." >&2
WIKI_SCRIPT=""
}
if [ -n "$WIKI_SCRIPT" ]; then
for each arxiv_id the user asked this skill to read in depth:
python3 "$WIKI_SCRIPT" ingest_paper research-wiki/ \
--arxiv-id "<arxiv_id>"
fi
fi
The helper handles metadata / slug / dedup / page / index / log in one
call — do not handwrite papers/<slug>.md. See
shared-references/integration-contract.md.
Backfill missed ingests with
python3 "$WIKI_SCRIPT" sync research-wiki/ --arxiv-ids <id1>,<id2>,...
after resolving $WIKI_SCRIPT as above.
Key Rules¶
- Prefer the adapter script over raw
deepxivcommands when available. - DeepXiv is optional. If unavailable, give the install command and suggest
/arxivor/research-lit "topic" - sources: web. - Use section-level reads to save tokens.
- Treat DeepXiv as complementary to
/arxivand/semantic-scholar, not a replacement. - If the result overlaps with a published venue paper from Semantic Scholar, keep the richer venue metadata in the final summary.