jcode/skills/scientific-deep-research/SKILL.md

name

description

scientific-deep-research

Literature research on a scientific question: find relevant papers (arXiv, OpenAlex, Semantic Scholar), prefer the peer-reviewed version of arXiv preprints (Crossref, dblp), download the PDFs, extract and read the text, and write research.md with structured per-paper summaries, a synthesis and a references.bib in BibTeX. Use for "survey the literature", "find papers on", "state of the art", "related work", or any task that needs citations.

Scientific deep research

Output: research.md (summaries + synthesis), references.bib, and the PDFs in papers/. Every claim in research.md is tied to a paper you actually opened; every BibTeX entry comes from a resolver, never from memory.

Tool: papers.py (stdlib only; pip install pymupdf for text). Copy it into the project: cp <skill-dir>/papers.py .. Be polite to the APIs: one call per second, CONTACT_EMAIL=you@uni.de in the environment.

Procedure

1. Frame the question in one sentence plus 3-6 search phrases (synonyms, method names, the application). Write them at the top of research.md.
2. Search: python papers.py search "<phrase>" --max 25 [--since 2018] for each phrase. Merged, deduplicated candidates land in candidates.json, ranked by citations (recent papers have few - don't drop them for that).
3. Screen by title + abstract (candidates.json): keep 8-15 papers that answer the question, including 2-3 recent ones and the most-cited classic. Note why each was kept in one line. Follow references of the best paper if coverage is thin (search with its key terms).
4. Resolve the citable version: python papers.py resolve <arxiv id | DOI | "title"> for every kept paper. For an arXiv preprint it looks for the journal or conference version (Semantic Scholar -> Crossref -> dblp) and prints which to cite. Cite the published version when one exists; otherwise cite the preprint and mark it (preprint) in research.md.
5. BibTeX: python papers.py bibtex <DOI | arXiv id | dblp key> -> append to references.bib. Keys are <lastname><year><firstword>; use exactly these keys in the text as [@key]. One entry per paper, no duplicates.
6. Download and read: python papers.py download <arxiv id | DOI> --out papers/ (arXiv PDF, or the open-access copy OpenAlex knows; otherwise say "no OA PDF" and work from the abstract, marked as such). Then python papers.py text papers/x.pdf and read the .txt with read_file in ranges: abstract, introduction, method, results tables, conclusion. Don't read reference lists.
7. Summarize each paper with the template below - numbers from the results, not adjectives. 120-200 words each.
8. Synthesize: what the field agrees on, where results conflict, which method fits the question, open problems. Reference papers by key.
9. Verify before finishing: every [@key] in research.md exists in references.bib and vice versa (grep -o '@\w*' research.md | sort -u against grep -o '^@\w*{\K[^,]*' references.bib); every summary names the version read (published / preprint / abstract only).

research.md template

# <Question>
Date, search phrases, databases, number screened / kept.

## Summary of findings (10-15 lines)
...with [@key] references...

## Papers
### <Title> [@key]
Authors, venue + year (or "arXiv preprint"), DOI/arXiv, read: full text | abstract only
- **Problem:** ...
- **Method:** ...
- **Data / setup:** ...
- **Results:** the numbers (metric, value, baseline, dataset)
- **Limitations:** stated by the authors or evident
- **Relevance to the question:** ...

## Synthesis
Agreement, contradictions, best-fit method, open questions.

## Not covered
Papers without accessible PDF, areas not searched.

## References
See references.bib (keys above).

Rules

• No citation without a resolved record. If a resolver finds nothing, the paper is "unverified" and goes into "Not covered", not into the text.
• Never "improve" numbers from memory; quote what the PDF says and the page.
• Preprint vs. published: results can differ between versions - say which one you read.
• Keep the PDFs and candidates.json; the user may want to continue.
• 10 well-read papers beat 40 abstracts. Stop searching when new queries return papers you already have.