---
name: scientific-deep-research
description: >
  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](./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
```markdown
# <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.