iomgaa
6bdb802f01
- Add all claude skills (brainstorming, commit, debugging, TDD, etc.) - Add claude hooks (pre-commit-guard, post-edit-quality) - Add research templates (experiment plan, research brief, etc.) - Add claude tools (arxiv/semantic_scholar/openalex fetch, wiki, exa) - Add TRM4 reference implementation as algorithm fidelity baseline - Add research-wiki content (plans, index, graph, query_pack) - Update .gitignore to exclude .graphify_version runtime state
214 lines
9.4 KiB
Markdown
214 lines
9.4 KiB
Markdown
---
|
|
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
|