Imported from middle-chunjie/mywiki (.aris/skill-sync/conflicts/20260503_155540/research-lit/SKILL.md). Install upstream with npx skills add middle-chunjie/mywiki --skill research-lit. Copyright stays with the author.

Research Literature Review

Research topic: $ARGUMENTS

Constants

• REVIEWER_BACKEND = codex — Default: Codex MCP (xhigh). Override with — reviewer: oracle-pro for GPT-5.4 Pro via Oracle MCP. See shared-references/reviewer-routing.md.
• WIKI_ROOT — Path to the MyWiki knowledge base. Default: the repository root (where wiki/ lives). Contains wiki/sources/*.md (structured paper pages) and wiki/concepts/*.md (concept pages with key points, contradictions, positions).
• MAX_WIKI_SOURCES = 30 — Maximum number of wiki source pages to include in results. Prioritize by frontmatter tag/domain match to the topic.
• PAPER_LIBRARY — Local directory containing user's paper collection (PDFs). Check these paths in order:
  1. papers/ in the current project directory
  2. literature/ in the current project directory
  3. Custom path specified by user in CLAUDE.md under ## Paper Library
• MAX_LOCAL_PAPERS = 20 — Maximum number of local PDFs to scan (read first 3 pages each). If more are found, prioritize by filename relevance to the topic.
• ARXIV_DOWNLOAD = false — When true, download top 3-5 most relevant arXiv PDFs to PAPER_LIBRARY after search. When false (default), only fetch metadata (title, abstract, authors) via arXiv API — no files are downloaded.
• ARXIV_MAX_DOWNLOAD = 5 — Maximum number of PDFs to download when ARXIV_DOWNLOAD = true.
• NO_WIKI = false — When true, skip the MyWiki read step (Step 0a) entirely. Literature survey runs pure external (web + local PDFs + external APIs). Use when you want a landscape-blind-to-MyWiki first pass, or when upstream skills (e.g., /idea-discovery) explicitly opt out of wiki background. When false (default), read MyWiki as Step 0a if wiki/sources/ exists.

💡 Overrides:

• /research-lit "topic" — paper library: ~/my_papers/ — custom local PDF path
• /research-lit "topic" — sources: wiki, local — only search wiki + local PDFs
• /research-lit "topic" — sources: wiki — only search wiki
• /research-lit "topic" — sources: web — only search the web (skip all local)
• /research-lit "topic" — no-wiki — skip MyWiki reading (Step 0a); pure external survey
• /research-lit "topic" — sources: web, semantic-scholar — also search Semantic Scholar for published venue papers (IEEE, ACM, etc.)
• /research-lit "topic" — sources: deepxiv — only search via DeepXiv progressive retrieval
• /research-lit "topic" — sources: all, deepxiv — use default sources plus DeepXiv
• /research-lit "topic" — arxiv download: true — download top relevant arXiv PDFs
• /research-lit "topic" — arxiv download: true, max download: 10 — download up to 10 PDFs

Data Sources

This skill checks multiple sources as peers. All are optional — if a source is not configured or not requested, skip it silently. Coverage varies per topic: wiki may be rich in some areas and empty in others, and fast-moving fields require fresh external search regardless of what is locally curated.

Source Selection

Parse $ARGUMENTS for a — sources: directive: <<<<<<< HEAD

• If — sources: is specified: Only search the listed sources (comma-separated). Valid values: zotero, obsidian, local, web, semantic-scholar, deepxiv, exa, gemini, openalex, all.
• If not specified: Default to all — search every available source in priority order (semantic-scholar, deepxiv, exa, gemini, and openalex are excluded from all; they must be explicitly listed). =======
• If — sources: is specified: Only search the listed sources (comma-separated). Valid values: wiki, local, web, semantic-scholar, deepxiv, exa, all.
• If not specified: Default to all — search every available source (semantic-scholar, deepxiv, and exa are excluded from all; they must be explicitly listed).

ours

Examples:

/research-lit "diffusion models"                                    → all (default)
/research-lit "diffusion models" — sources: wiki                    → wiki only
/research-lit "diffusion models" — sources: wiki, web               → wiki + web
/research-lit "diffusion models" — sources: local                   → local PDFs only
/research-lit "topic" — sources: web                                → web only (skip wiki + local)
/research-lit "topic" — sources: web, semantic-scholar              → web + S2 API
/research-lit "topic" — sources: deepxiv                            → DeepXiv only
/research-lit "topic" — sources: all, deepxiv                       → default sources + DeepXiv
/research-lit "topic" — sources: all, semantic-scholar              → all + S2 API
<<<<<<< HEAD
/research-lit "topic" — sources: exa                               → Exa only (broad web + content extraction)
/research-lit "topic" — sources: all, exa                          → default sources + Exa web search
/research-lit "topic" — sources: gemini                            → Gemini only (AI-powered broad discovery)
/research-lit "topic" — sources: all, gemini                       → default sources + Gemini discovery
/research-lit "topic" — sources: gemini, semantic-scholar           → Gemini + S2 (broad discovery + venue metadata)
/research-lit "topic" — sources: openalex                          → OpenAlex only (open citation graph + institutions)
/research-lit "topic" — sources: semantic-scholar, openalex         → S2 + OpenAlex (complementary metadata)
=======
/research-lit "topic" — sources: exa                                → Exa only
/research-lit "topic" — sources: all, exa                           → default sources + Exa
>>>>>>> ours

Source Table

<<<<<<< HEAD

ours

Graceful degradation: If wiki/ doesn't exist, skip to local PDFs + web search. Each source is independent.

Workflow

Step 0a: Search MyWiki Knowledge Base (if available)

Skip this step entirely if:

• wiki/sources/ directory does not exist, OR
• NO_WIKI = true (via — no-wiki flag or inherited from caller)

When skipped due to — no-wiki, note in the final landscape summary: "MyWiki background skipped (--no-wiki flag)".

1. Search sources by topic: Glob wiki/sources/*.md. For each, read frontmatter (title, tags, domain, year) and match against the research topic keywords. Prioritize by tag/domain match.

2. Extract from matched sources (up to MAX_WIKI_SOURCES):

   • Title, authors, year, venue (from frontmatter)
   • ## Summary — first 2-3 sentences (the user's curated summary)
   • ## Key Contributions — what the paper does
   • ## My Notes — the user's personal annotations (gold — shows what they found important)

3. Search concepts: Glob wiki/concepts/*.md. Match by tags/domain. For matched concepts:

   • ## Key Points — established knowledge in this area
   • ## Contradictions — unresolved debates
   • ## My Position — the user's stance

4. Compile results: For each relevant wiki entry, extract:

   • Title, authors, year, venue
   • User's summary and notes (if any)
   • Which concepts it connects to
   • Confidence level (low/medium/high)

Wiki sources represent the user's curated, structured knowledge — higher signal than raw PDFs or web search snippets. Use them to understand what the user already knows and where the gaps are.

Step 0b: Scan Local Paper Library

Before searching online, check if the user already has relevant papers locally:

1. Locate library: Check PAPER_LIBRARY paths for PDF files

   Glob: papers/**/*.pdf, literature/**/*.pdf
   

2. De-duplicate against wiki: If Step 0a found papers, skip any local PDFs already covered by wiki results (match by filename or title).

3. Filter by relevance: Match filenames and first-page content against the research topic. Skip clearly unrelated papers.

4. Summarize relevant papers: For each relevant local PDF (up to MAX_LOCAL_PAPERS):

   • Read first 3 pages (title, abstract, intro)
   • Extract: title, authors, year, core contribution, relevance to topic
   • Flag papers that are directly related vs tangentially related

5. Build local knowledge base: Compile summaries into a "papers you already have" section. This becomes the starting point — external search fills the gaps.

📚 If no local papers are found, skip to Step 1. If the user has a comprehensive local collection, the external search can be more targeted (focus on what's missing).

Step 1: Search (external)

• Use WebSearch to find recent papers on the topic
• Check arXiv, Semantic Scholar, Google Scholar
• Focus on papers from last 2 years unless studying foundational work
• De-duplicate: Skip papers already found in wiki or local library

arXiv API search (always runs, no download by default):

Locate the fetch script and search arXiv directly:

# Try to find arxiv_fetch.py
SCRIPT=$(find tools/ -name "arxiv_fetch.py" 2>/dev/null | head -1)
# If not found, check ARIS install
[ -z "$SCRIPT" ] && SCRIPT=$(find ~/.claude/skills/arxiv/ -name "arxiv_fetch.py" 2>/dev/null | head -1)

# Search arXiv API for structured results (title, abstract, authors, categories)
python3 "$SCRIPT" search "QUERY" --max 10

If arxiv_fetch.py is not found, fall back to WebSearch for arXiv (same as before).

The arXiv API returns structured metadata (title, abstract, full author list, categories, dates) — richer than WebSearch snippets. Merge these results with WebSearch findings and de-duplicate.

arXiv cascade (see /arxiv skill for full protocol): if the arXiv API returns an error, 429, empty-despite-valid-query, or a chronological feed ignoring the query, automatically fall back in this order: mcp__deepxiv__search_papers → mcp__paper-search-mcp__search_arxiv → WebSearch with site:arxiv.org. Do not ask the user to switch — switch silently and note the fallback in the final summary.

Semantic Scholar API search (only when semantic-scholar is in sources):

When the user explicitly requests — sources: semantic-scholar (or — sources: web, semantic-scholar), search for published venue papers beyond arXiv:

S2_SCRIPT=$(find tools/ -name "semantic_scholar_fetch.py" 2>/dev/null | head -1)
[ -z "$S2_SCRIPT" ] && S2_SCRIPT=$(find ~/.claude/skills/semantic-scholar/ -name "semantic_scholar_fetch.py" 2>/dev/null | head -1)

# Search for published CS/Engineering papers with quality filters
python3 "$S2_SCRIPT" search "QUERY" --max 10 \
  --fields-of-study "Computer Science,Engineering" \
  --publication-types "JournalArticle,Conference"

If semantic_scholar_fetch.py is not found, skip silently.

Why use Semantic Scholar? Many IEEE/ACM journal papers are NOT on arXiv. S2 fills the gap for published venue-only papers with citation counts and venue metadata.

De-duplication between arXiv and S2: Match by arXiv ID (S2 returns externalIds.ArXiv):

• If a paper appears in both: check S2's venue/publicationVenue — if it has been published in a journal/conference (e.g. IEEE TWC, JSAC), use S2's metadata (venue, citationCount, DOI) as the authoritative version, since the published version supersedes the preprint. Keep the arXiv PDF link for download.
• If the S2 match has no venue (still just a preprint indexed by S2): keep the arXiv version as-is.
• S2 results without externalIds.ArXiv are venue-only papers not on arXiv — these are the unique value of this source.

DeepXiv search (only when deepxiv is in sources):

When the user explicitly requests — sources: deepxiv (or includes deepxiv in a combined source list), use the DeepXiv adapter for progressive retrieval:

python3 tools/deepxiv_fetch.py search "QUERY" --max 10

Then deepen only for the most relevant papers:

python3 tools/deepxiv_fetch.py paper-brief ARXIV_ID
python3 tools/deepxiv_fetch.py paper-head ARXIV_ID
python3 tools/deepxiv_fetch.py paper-section ARXIV_ID "Experiments"

If tools/deepxiv_fetch.py or the deepxiv CLI is unavailable, skip this source gracefully and continue with the remaining requested sources.

Why use DeepXiv? It is useful when a broad search should be followed by staged reading rather than immediate full-paper loading. This reduces unnecessary context while still surfacing structure, TLDRs, and the most relevant sections.

De-duplication against arXiv and S2:

• Match by arXiv ID first, DOI second, normalized title third
• If DeepXiv and arXiv refer to the same preprint, keep one canonical paper row and record deepxiv as an additional source
• If DeepXiv overlaps with S2 on a published paper, prefer S2 venue/citation metadata in the final table, but keep DeepXiv-derived section notes when they add value

Exa search (only when exa is in sources):

When the user explicitly requests — sources: exa (or includes exa in a combined source list), use the Exa tool for broad AI-powered web search with content extraction:

EXA_SCRIPT=$(find tools/ -name "exa_search.py" 2>/dev/null | head -1)

# Search for research papers with highlights
python3 "$EXA_SCRIPT" search "QUERY" --max 10 --category "research paper" --content highlights

# Search for broader web content (blogs, docs, news)
python3 "$EXA_SCRIPT" search "QUERY" --max 10 --content highlights

If tools/exa_search.py or the exa-py SDK is unavailable, skip this source gracefully and continue with the remaining requested sources.

Why use Exa? Exa provides AI-powered search across the broader web (blogs, documentation, news, company pages) with built-in content extraction. It fills a gap between academic databases (arXiv, S2) and generic WebSearch by returning richer content with each result.

De-duplication against arXiv, S2, and DeepXiv:

• Match by URL first, then normalized title
• If Exa returns an arXiv paper already found by arXiv/S2, prefer the structured metadata from those sources
• Exa results from non-academic domains (blogs, docs, news) are unique value not covered by other sources

Gemini search (only when gemini is in sources):

When the user explicitly requests — sources: gemini (or includes gemini in a combined source list), use Gemini for AI-powered broad literature discovery.

Priority 1 — Gemini MCP (preferred): Call mcp__gemini-cli__ask-gemini with the search prompt:

mcp__gemini-cli__ask-gemini({
  prompt: 'You are a research literature scout. Search comprehensively for papers on: "QUERY"

IMPORTANT CONSTRAINTS:
1. Search from MULTIPLE angles — decompose the topic into sub-problems, aliases, neighboring tasks, and common benchmark/settings variants.
2. Prefer papers that are genuinely relevant, not merely keyword-adjacent.
3. Include top venues, journals, surveys, recent preprints, and papers with code when available.
4. Focus on papers from 2022 onward unless older foundational work is necessary.

For EACH paper found, provide ALL of the following:
- Title: [exact title]
- Authors: [full author list]
- Year: [publication year]
- Venue: [exact conference/journal name + year, or "arXiv preprint"]
- arXiv ID: [format 2401.12345, or "N/A"]
- DOI: [if available, or "N/A"]
- Code URL: [GitHub/GitLab link if available, or "No code"]
- Summary: [one-sentence core contribution]

Find at least 15 papers.',
  model: 'gemini-2.5-pro'
})

Priority 2 — Gemini CLI fallback (if MCP unavailable): Use gemini -p "...same prompt..." 2>/dev/null via Bash (timeout: 120s).

If both MCP and CLI are unavailable, skip this source gracefully and continue with the remaining requested sources.

Why use Gemini? Gemini provides AI-driven discovery that goes beyond keyword matching — it decomposes topics, explores naming variants, and surfaces papers that traditional API-based searches (arXiv, S2) may miss. It fills a different retrieval niche from structured database queries.

De-duplication against arXiv, S2, DeepXiv, and Exa:

• Match by arXiv ID first, DOI second, normalized title third
• If Gemini returns a paper already found by S2, prefer S2's citation count and venue metadata
• If Gemini returns a paper already found by arXiv, prefer arXiv's structured metadata
• Gemini's unique value is discovering papers that other keyword-based indexes did not surface
• Do not use Gemini-reported citation counts — they may be inaccurate. Use S2 for authoritative citation data.

OpenAlex search (only when openalex is in sources):

When the user explicitly requests — sources: openalex (or includes openalex in a combined source list), use OpenAlex API for comprehensive academic metadata:

OA_SCRIPT=$(find tools/ -name "openalex_fetch.py" 2>/dev/null | head -1)

# Preflight: skip OpenAlex silently if either openalex_fetch.py or the
# `requests` Python package is unavailable. Both checks must pass before
# the script is invoked, so users without `requests` installed never see
# a stack trace from a default `/research-lit` run.
if [ -z "$OA_SCRIPT" ] || ! python3 -c "import requests" >/dev/null 2>&1; then
  echo "OpenAlex source not available (missing tools/openalex_fetch.py or 'requests' module); skipping." >&2
else
  # Search for papers with comprehensive metadata
  python3 "$OA_SCRIPT" search "QUERY" --max 10 \
    --year "2022-" \
    --type article \
    --sort relevance
fi

If openalex_fetch.py is not found or requests module is missing, skip this source gracefully and continue with the remaining requested sources.

Why use OpenAlex? Fully open citation graph (no API key required), institutional affiliations, funding data (NSF, NIH), comprehensive topic/keyword metadata, and coverage across all disciplines (not just CS).

De-duplication against arXiv, S2, DeepXiv, Exa, and Gemini:

• Match by DOI first (OpenAlex has DOI for most works), then arXiv ID, then normalized title
• If OpenAlex and S2 both have the same paper:
  • Prefer S2 for citation counts (more up-to-date)
  • Prefer S2 for venue metadata (more accurate for CS/AI papers)
  • Use OpenAlex for institutional affiliations and funding data (unique value)
  • Merge both into a richer record
• If OpenAlex and arXiv overlap, prefer arXiv's PDF link and metadata, but keep OpenAlex's citation/institution data
• OpenAlex's unique value: institutional affiliations, funding sources, comprehensive topic classification, and cross-discipline coverage

Optional PDF download (only when ARXIV_DOWNLOAD = true):

After all sources are searched and papers are ranked by relevance:

# Download top N most relevant arXiv papers
python3 "$SCRIPT" download ARXIV_ID --dir papers/

• Only download papers ranked in the top ARXIV_MAX_DOWNLOAD by relevance
• Skip papers already in the local library
• 1-second delay between downloads (rate limiting)
• Verify each PDF > 10 KB

Step 2: Analyze Each Paper

For each relevant paper (from all sources), extract:

• Problem: What gap does it address?
• Method: Core technical contribution (1-2 sentences)
• Results: Key numbers/claims
• Relevance: How does it relate to our work?
• Source: Where we found it (wiki/local/web) — helps user know what they already have vs what's new

Step 3: Synthesize

• Group papers by approach/theme
• Identify consensus vs disagreements in the field
• Find gaps that our work could fill
• If wiki concept notes exist, incorporate the user's own insights into the synthesis

Step 4: Output

Present as a structured literature table:

| Paper | Venue | Method | Key Result | Relevance to Us | Source |
|-------|-------|--------|------------|-----------------|--------|

Plus a narrative summary of the landscape (3-5 paragraphs).

Step 5: Save (if requested)

• Save paper PDFs to literature/ or papers/
• Update related work notes in project memory

<<<<<<< HEAD

Step 6: Update Research Wiki

Required when research-wiki/ exists. Skip entirely (no action, no error) if the directory is absent. Per shared-references/integration-contract.md, this step follows the canonical ingest contract — business logic lives in tools/research_wiki.py, not in this prose.

Step 6: Stage Papers for Wiki Writeback (MyWiki projects)

Required when inside a MyWiki project (walk up from cwd looking for projects/<slug>/wiki-contributions/). Skip silently if not in a MyWiki project.

ours

For each of the top 8–12 relevant papers surfaced this run:

1. Append a markdown entry to projects/<slug>/wiki-contributions/pending-sources.md under a date-stamped section:

## <YYYY-MM-DD> | /research-lit
- **Title**: <full title>
  arxiv: <id> | authors: <First, Second, ...> | year: <YYYY> | venue: <venue>
  thesis: <one-line claim>
  tags: <tag1, tag2, ...>
  relevance: <one-line why this matters for the current project>

<<<<<<< HEAD 📋 Research Wiki ingest (runs once, at end of research-lit): [ ] 1. Predicate: research-wiki/ exists? If no, skip this step. [ ] 2. For each of the top 8–12 relevant papers (arxiv IDs collected above): python3 tools/research_wiki.py ingest_paper research-wiki/
--arxiv-id [--thesis ""] [--tags ,] [ ] 3. For each explicit relationship to an existing wiki entity, add an edge: python3 tools/research_wiki.py add_edge research-wiki/
--from "paper:" --to "<target_node_id>"
--type <extends|contradicts|addresses_gap|inspired_by|...>
--evidence "" [ ] 4. Confirm papers/.md files were created (helper prints "Paper ingested: ..."); if any failed with a network error, retry or fall back to the --title/--authors/--year manual form.

`ingest_paper` handles slug generation, arXiv metadata fetch, dedup
(skips an existing paper by arXiv id), page rendering, `index.md`
rebuild, `query_pack.md` rebuild, and log append in a single call —
**do not manually write `papers/<slug>.md`**. If the helper is
unavailable (e.g., offline on a non-ARIS machine), log the gap and let
`/research-wiki sync --arxiv-ids …` backfill later.

For non-arXiv sources (Semantic Scholar only, IEEE/ACM journals without
arXiv mirrors, blog posts), pass manual metadata instead:

python3 tools/research_wiki.py ingest_paper research-wiki/
--title "" --authors "A, B, C" --year
--venue "" [--external-id-doi ""] [--thesis "..."]

2. Log to JOURNAL.md:

ours

- **[finding]** research-lit surfaced N papers; staged to wiki-contributions/pending-sources.md

3. Rebuild MEMORY.md so downstream skills see the new papers:

python3 scripts/project_memory.py rebuild --slug <slug>

The user's /project-writeback skill handles the MyWiki-sources upgrade path — do NOT write directly to wiki/sources/ from here.

Key Rules

• Always include paper citations (authors, year, venue)
• Distinguish between peer-reviewed and preprints
• Be honest about limitations of each paper
• Note if a paper directly competes with or supports our approach
• Never fail because a source is not available — always fall back gracefully to the next data source