---
name: research-lit
description: "Search and analyze research papers, literature reviews, and related work. Trigger phrases: find papers, literature review, related work, literature review."
argument-hint: [research-topic]
---

# Literature Review
Research topic: $ARGUMENTS

## Constants
- `PAPER_LIBRARY = references/` (local PDF directory)
- `MAX_LOCAL_PAPERS = 20`

## Data Sources (all enabled by default)

| Data source | How to determine availability | What it provides | Fallback behavior |
|---|---|---|---|
| Local PDF | `references/` exists and `references/**/*.pdf` is non-empty | Papers, reports, appendices, and drafts collected in the repo | Read only locally; if there are no PDFs, continue with online search |
| Web search | Network is available and general search results are accessible | Google Scholar / paper pages / arXiv / conference homepages / survey blogs | If search fails, skip that source and keep results from others |
| arXiv API | `python3 .claude/tools/arxiv_fetch.py` is runnable and the network is available | arXiv metadata, abstracts, IDs, categories, versions | Skip if unavailable; prefer arXiv records from other sources |
| Semantic Scholar | `python3 .claude/tools/semantic_scholar_fetch.py` is runnable and the network is available | Paper metadata, venue, citation, author, and citation relationships | Skip if unavailable; if an arXiv paper has S2 venue metadata, prefer S2 |
| Exa | `python3 .claude/tools/exa_search.py` is runnable, the network is available, and API config exists | Semantic search, page highlight excerpts, related paper page clues | Skip if unavailable; use results only as supplemental clues |
| OpenAlex | `python3 .claude/tools/openalex_fetch.py` is runnable and the network is available | Open scholarly graph, DOI, venue, year, and citation relationships | Skip if unavailable; use it to fill in DOI / venue / author information |
| DeepXiv | `python3 .claude/tools/deepxiv_fetch.py` is runnable and the network is available | Semantic search and paper aggregation results focused on arXiv | Skip if unavailable; cross-check against arXiv / S2 |

### Coverage Control
All data sources are enabled by default. If the user includes the instruction:

`— sources: <list>`

then only the sources listed in `<list>` are used. Parsing rules:

- `<list>` is comma-separated and may use Chinese or English names, such as `local PDF, arXiv, Semantic Scholar`
- Keep only recognizable names; ignore unknown items
- If parsing yields nothing, fall back to the default of enabling everything
- Either local-only reading or online-only searching is allowed; do not stop because some sources are unavailable

## Workflow

### Step 0: Scan local PDFs

Scan the local library first, then decide where to focus online search.

1. Glob: `references/**/*.pdf`
2. Filter by relevance to the research topic, prioritizing PDFs whose title, abstract, first chapter, or conclusion matches the topic
3. For up to `MAX_LOCAL_PAPERS` relevant PDFs, read the first 3 pages
4. Record the title, authors, year, venue, method keywords, and relevance for each paper

Recommended reading command:

```bash
python3 tools/read_pdf_pages.py references/path/to/paper.pdf --pages 1-3
```

If the repository does not include that script, use any available PDF-reading tool or existing command. The rule is to read only the first 3 pages and avoid blind full-document reading.

### Step 1: Online search

Run retrieval for each enabled data source. Commands should be structured as closely as possible to the following forms. `QUERY` should be replaced with a search string built around the research topic, including the task noun, core method, aliases, synonyms, and common abbreviations.

- `python3 .claude/tools/arxiv_fetch.py search "QUERY" --max 10`
- `python3 .claude/tools/semantic_scholar_fetch.py search "QUERY" --max 10`
- `python3 .claude/tools/exa_search.py search "QUERY" --max 10 --category "research paper" --content highlights`
- `python3 .claude/tools/openalex_fetch.py search "QUERY" --max 10 --year "2022-"`
- `python3 .claude/tools/deepxiv_fetch.py search "QUERY" --max 10`
- WebSearch for Google Scholar / the general web

Search strategy:

1. Start with broad queries to identify the main direction
2. Use narrower queries to find recent work, SOTA, benchmarks, surveys, and ablations from the last two years
3. Add controversy points, failure cases, negative results, and competing methods
4. Record raw results from each source; do not drop borderline candidates too early

### Step 2: Cross-source deduplication

Deduplicate in this order:

1. `arXiv ID`
2. `DOI`
3. normalized title

Rules:

- Normalize titles by lowercasing, removing punctuation, removing extra spaces, and removing version suffixes
- If the same paper has different metadata across sources, keep the record with the most complete information
- If `S2` (Semantic Scholar) provides venue, year, author, or citation metadata for an arXiv paper, prefer those fields from `S2`
- Distinguish between preprints and formally published versions; if both correspond to the same research, record the relationship but ultimately prefer the more authoritative published version

### Step 3: Analyze each paper

For each retained paper, extract:

- `problem/gap`: what problem is being solved and what existing methods are missing
- `method`: core idea, model, training / inference flow, and key tricks
- `key results`: main experimental findings, metrics, baselines, and datasets
- `relevance to our work`: the direct connection to the current research topic and what can be borrowed
- `source`: which source or sources the paper came from and whether metadata conflicts exist

Requirements:

- Every paper must include author, year, and venue
- Explicitly mark `preprint`, `conference paper`, `journal paper`, `workshop`, and similar statuses
- If author / year / venue is uncertain, state the source of uncertainty and do not fabricate it

### Step 4: Synthesis

Cluster papers by method route or theme instead of sorting only by time.

The synthesis must answer:

- Which method routes have become the consensus
- Where the important disagreements are
- Which conclusions hold only for specific datasets or settings
- What gaps remain unsolved
- Which results matter most for our research, and why

Prioritize:

- Work from the last 2 years
- Representative methods and accepted baselines for the direction
- Ablations, diagnostics, and failure analyses that explain performance differences

If the topic is foundational or classical, trace back to the original work, but keep the newest work as the main line.

### Step 5: Output

The final output must include both:

1. A structured literature table
2. A 3-5 paragraph narrative summary

Suggested table columns:

- Paper
- Authors / Year / Venue
- Source
- Problem / Gap
- Method
- Key Results
- Relevance to Our Work

The narrative should:

- Summarize the sub-branches of the topic first, then the consensus and disagreements
- Clearly call out the 3-5 papers worth following next
- Clearly identify 1-3 gaps that can become future research entry points

### Step 6: Wiki Integration

First check whether `research-wiki/` exists; if it does not, skip all writes without error.

If it does exist, then:

1. Ingest the top 8-12 papers into the wiki

```bash
.claude/tools/research_wiki.py ingest_paper research-wiki/ --arxiv-id <id> [--title "..." --authors "..." --year ...]
```

2. Create entities for identified gaps

```bash
.claude/tools/research_wiki.py add_entity research-wiki/ --type gap --id <slug> --title "..."
```

3. Add paper relationship edges

```bash
.claude/tools/research_wiki.py add_edge research-wiki/ --from "paper:X" --to "paper:Y" --type extends --evidence "..."
```

4. Rebuild the query pack and index

```bash
.claude/tools/research_wiki.py rebuild_query_pack research-wiki/ && .claude/tools/research_wiki.py rebuild_index research-wiki/
```

Integration rules:

- Only write papers with high confidence and highest topic relevance into the wiki
- Gap node names should be short and stable so they can be reused later
- Relationship edges must include evidence; do not create vague connections

## Key Rules

- Always cite papers: author, year, and venue are required
- Distinguish peer-reviewed papers from preprints
- Missing tools, missing APIs, or missing network access must degrade gracefully; never stop because one source fails
- Focus on the last 2 years by default; only trace back further when the task is about foundational work
- Do not just list papers; summarize the thread, disagreements, and gaps
- If the query is too narrow, first expand with synonyms, abbreviations, and higher-level terms, then narrow again to a precise sub-direction
- If there are too many results, keep representative, highly cited, newer, stronger-experiment, and closest-to-topic papers first
- If there are too few results, broaden the query and rescan relevant PDFs in the local library

## Execution Standard

- Local first, then online
- Deduplicate first, then analyze
- Evidence first, then conclusions
- Cluster first, then narrate
- Integrate the wiki first, then finish

## Completion Criteria

Only finish the task when all of the following are complete:

1. Local PDF scanning is complete
2. At least the default-enabled data sources were covered, or fallback reasons were recorded
3. Deduplication is complete
4. Every core paper has been analyzed
5. A table and narrative summary were produced
6. If `research-wiki/` exists, the corresponding writes and rebuilds were completed
