chore: track claude skills, tools, templates, reference code and research-wiki
- 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
This commit is contained in:
@@ -0,0 +1,213 @@
|
||||
---
|
||||
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
|
||||
Reference in New Issue
Block a user