/citation-graph

name: citation-graph
description: "Expand a set of key papers into the literature around them by walking the citation graph with the Semantic Scholar and OpenAlex APIs: backward (references), forward (citing works), and co-citation, scored by how many seeds connect to each candidate, so the papers a reviewer will expect are found even when keyword search misses them. Use after literature-search has found the first key papers, when a supervisor names one seminal paper, or when checking that a related-work chapter has not missed a line of work."
argument-hint: "(optional) seed DOIs, arXiv ids, or keys from the .bib; add --depth 1|2 and --min-links N"

Keyword search finds papers that use your words; the citation graph finds papers that share your problem. Starting from a few papers known to be central, the works they cite and the works that cite them, weighted by how many seeds agree, surface the field's structure and its recent edge.

Inputs

Seeds: DOIs, arXiv ids, Semantic Scholar ids, or `.bib` keys (resolved through `references.bib`). Three to eight seeds work best; one seed gives a star, not a graph. Options: `--depth` (1: neighbours of seeds; 2: neighbours of the strongest first-degree candidates; default 1), `--min-links` (minimum seed connections to keep a candidate; default 2), `--since YEAR` for the forward direction.

Procedure

1. **Resolve seeds** to Semantic Scholar paper ids: `curl -s "https://api.semanticscholar.org/graph/v1/paper/DOI:<doi>?fields=paperId,title,year,citationCount"`. 2. **Backward**: for each seed, `/paper/<id>/references?fields=paperId,title,year,externalIds,citationCount,influentialCitationCount&limit=500`. Tally each referenced paper's seed count. 3. **Forward**: for each seed, `/paper/<id>/citations?fields=...&limit=1000` (page with `offset` when over 1000; apply `--since`). Tally. 4. **Co-citation** (optional, strong signal): for the top forward candidates, fetch their references and count how often two seeds appear together; candidates cited alongside the seeds by many papers belong to the same conversation. 5. **Score** each candidate: `links` (distinct seeds connected), `influential` (Semantic Scholar's influential-citation flag counts double), citations normalised by age, and recency for the forward set. Show the formula. 6. **Depth 2**: take the top ten candidates by score, treat them as seeds, repeat steps 2 and 3, and keep only candidates linked to at least two of the original seeds. 7. **Cross-check** each kept candidate with OpenAlex (`api.openalex.org/works/doi:<doi>`) for the DOI, venue, and open-access link; drop anything that does not resolve. 8. Rate-limit: one request per second; on 429 wait and retry. Cache responses under `research/.graph-cache/` keyed by paper id.

Output

`research/citation-graph.md`:

# Citation graph from 5 seeds (2026-09-21, depth 1, min-links 2)

Seeds: smith2023feedback, lee2022grading, ...

## Backward (cited by the seeds)
| links | year | citations | title | DOI |
| 4 | 2015 | 1,203 | Foundations of ... | 10.x |
...

## Forward (cite the seeds), since 2022
...

## Co-cited with the seeds
...

## Reading recommendations
- 10.x (links 4): cited by four of five seeds; a foundational paper the related-work chapter must position against.
- ...

## Lines of work the seeds share
Two or three sentences per cluster visible in the table (same venue, same authors, same method).

Then hand the recommended papers to `bibtex-manager` (add) and `paper-reader` (notes).

Rules

• Never add a candidate to the reading list without a resolvable identifier.
• Report the counts (how many references and citations were walked) so the search log in the method chapter can state the coverage.
• Highly cited is not the same as relevant; the `links` column is the relevance signal, citations are the weight.