Bib Coverage

Bibliography Coverage

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

Compare a project's .bib file against a Paperpile label 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 label, to find items not yet in any project's .bib
• After /bib-validate, as a complementary check (validate checks quality; coverage checks completeness)

When NOT to Use

• Finding new references — use /literature for discovery
• Validating .bib quality (missing fields, DOI issues, preprint staleness) — use /bib-validate
• Building a .bib from scratch — use /literature or /bib-parse

Inputs

1. Project .bib file — detected automatically (same logic as /bib-validate: look for references.bib, then any .bib in the project)
2. Paperpile label — resolved from:
   • Explicit --topic <slug> argument
   • Project's AGENTS.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 Label

1. Call paperpile get-labels to find the relevant topic label
2. Call paperpile get-items-by-label to get items in that label
3. Extract item keys (citekey) and titles

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

3. Compare

Produce three lists:

4. Coverage Stats

## Coverage Report

**Paperpile label:** [label name] ([N] items)
**Project .bib:** [M] entries

| Metric | Count | % |
|--------|-------|---|
| Cited + In Label | X | X/N |
| Cited but Not Labelled | Y | — |
| In Label, Not Cited | Z | Z/N |
| Coverage (cited/label) | — | 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. Run /bib-validate fix mode to file them."
• 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 label
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

• /bib-validate — Quality validation (missing fields, DOIs, preprints). Run alongside coverage for a complete check.
• /literature — 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