bib-coverage

name	bib-coverage
description	Compare a project .bib against a Paperpile project/topic folder to find uncited papers or unfiled entries. Use when the user asks to compare a project .bib against a Paperpile project/topic folder to find uncited papers or unfiled entries.
allowed-tools	Read, Glob, Grep, Bash(paperpile*)
argument-hint	[project-path or tex-file]

Bibliography Coverage

LIBRARY-FIRST RULE: ALWAYS check Paperpile (paperpile search-library) when assessing coverage.

Compare a project's .bib file against a Paperpile project/topic folder to identify gaps between the project bibliography and the reference library.

When to Use

• After a literature search, to see what % of the topic collection is cited
• Before submitting a paper, to catch references you forgot to cite
• When reviewing a Paperpile project/topic folder, to find items not yet in any project's .bib
• After a bibliography-quality check, as a complementary completeness check

When NOT to Use

• Finding new references — use an installed literature-discovery workflow or scholarly search
• Validating .bib quality (missing fields, DOI issues, preprint staleness) — use an installed bibliography validator
• Building a .bib from scratch — use bib-parse or an installed literature workflow

Inputs

1. Project .bib file — detected automatically (same logic as bib-validate: look for references.bib, then any .bib in the project)
2. Paperpile folder — resolved from:
   • Explicit --topic <slug> argument
   • Project's CLAUDE.md or Atlas topic frontmatter
   • Directory name if inside a research project
   • If no collection can be resolved, report an error and suggest specifying --topic

Workflow

1. Load Project Bibliography

Parse the .bib file to extract all entry keys and titles.

2. Load Paperpile Folder

1. Call paperpile get-folders to find the relevant full topic path
2. Call paperpile get-items-by-folder "<full path>" to get items in that folder
3. Extract item keys (citekey) and titles

Paperpile's labelsNamed and foldersNamed are distinct. Project/topic collections use folders. If a leaf occurs under multiple parents, stop and request or derive the full path; never silently choose one.

Graceful degradation: If the paperpile CLI is unavailable, skip with a warning — report .bib-only stats.

3. Compare

Produce three lists:

Category	Description	Action
Cited + In Folder	Items in both .bib and the Paperpile folder	No action — healthy
Cited but Not in Folder	Items in .bib but not in the Paperpile folder	Needs filing in Paperpile
In Folder but Not Cited	Items in the Paperpile folder but not cited in any .tex	Potential references — review for inclusion

4. Coverage Stats

## Coverage Report

**Paperpile folder:** [full path] ([N] items)
**Project .bib:** [M] entries

| Metric | Count | % |
|--------|-------|---|
| Cited + In Folder | X | X/N |
| Cited but Not Filed | Y | — |
| In Folder, Not Cited | Z | Z/N |
| Coverage (cited/folder) | — | X/N% |

5. Recommendations

Based on the results:

• Low coverage (<50%): "The project cites few papers from the topic collection. Consider reviewing uncited items for relevance."
• Many unfiled citations (>5): "Several cited papers aren't in the topic collection. Reconcile them with the configured reference manager."
• High coverage (>80%): "Good coverage of the topic collection."

Report Format

## bib-coverage: [Project Name]

**Topic:** [slug] | **Collection:** [name] ([N] items) | **Bib:** [filename] ([M] entries)

### Coverage: X/N (XX%)

### Cited but Not in Collection (need filing)
| # | Key | Title | Year |
|---|-----|-------|------|

### In Collection but Not Cited (potential references)
| # | Key | Title | Year |
|---|-----|-------|------|

Phase 6 (Optional): Gap Discovery via Recommendations

When coverage is low (<50%) or the user says "find what I'm missing", use the S2 Recommendations API to discover papers that should be in the collection but aren't.

1. Select seed papers — pick the 3-5 most-cited papers from the .bib file
2. Get recommendations — run scholarly scholarly-similar-works <paper_id> --json for each seed paper to get ML-based similar paper suggestions
3. Filter against existing — remove papers already in the .bib or Paperpile folder
4. Rank by relevance — sort by citation count and recency
5. Present candidates — show a table of recommended additions with titles, years, citation counts

Dispatch rule. If ≥5 seed papers are selected, dispatch a single Explore sub-agent that runs scholarly scholarly-similar-works for each seed and writes merged candidates to /tmp/bib-coverage-similar.json. Main context reads only the merged result. For 3–4 seeds, inline calls are fine. See _shared/cli-dispatch-policy.md.

This turns a passive coverage check into an active discovery tool — finding papers the researcher should know about based on what they already cite.

Cross-References

• Installed bibliography validator — Quality validation (missing fields, DOIs, preprints). Run alongside coverage for a complete check.
• Installed literature workflow — Discovery of new references. Coverage identifies gaps in existing collections.
• bib-parse — Extract citations from PDFs. Run coverage after parsing to see overlap with the topic collection.
• shared/reference-resolution.md — Topic collection resolution logic