# Bib Validate

> Use when you need to validate a paper's bibliography — cross-references \\cite{} keys against .bib files or embedded \\bibitem entries, finds missing/unused/typo'd keys, and checks every key against the Paperpile library via the local resolver. Deep verification mode spawns parallel agents for DOI/metadata validation at scale. Fix mode rekeys drifted keys to canonical and stages missing entries f…

- **Type:** Skill
- **Install:** `agentstack add skill-flonat-flonat-research-bib-validate`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [flonat](https://agentstack.voostack.com/s/flonat)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [flonat](https://github.com/flonat)
- **Source:** https://github.com/flonat/flonat-research/tree/main/skills/bib-validate

## Install

```sh
agentstack add skill-flonat-flonat-research-bib-validate
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Bibliography Validation

**LIBRARY-FIRST RULE: ALWAYS cross-reference all `.bib` keys against Paperpile during validation** — via ONE dry-run of `scripts/bib/rekey_to_canonical.py` (Task-Management; matches the local library JSON in ~5s), NOT per-key `paperpile search-library` loops or lookup sub-agents. This catches key drift between the `.bib` file and the reference manager. See the Reference Manager Cross-Reference section.

## Output Path

Per `rules/review-artefact-routing.md` (auto-loads in research projects (path-scoped to `paper-*/` and `paper/`)):

- **Source slug:** `bib-validate`
- **Write reports to:** `reviews//bib-validate/.md` inside the project (where `` is the paper directory slug, e.g., `paper-jtp`, `paper-philtech`). Path is relative to the research project root, not the Task-Management repo.
- **Never** at project root (`./CRITIC-REPORT.md`-style filenames are forbidden — pre-rule layout).
- **Idempotency:** if today's file exists, append a same-day descriptor (`{date}-revision.md`, `{date}-r2.md`, `{date}-pre-submission.md`) — never overwrite.
- **Index update:** if `reviews/INDEX.md` exists, write a one-line entry under "Latest per source" pointing at the new file. Otherwise `/review-recap` will rebuild the index next time it runs.
- **Infrastructure repos** (Task-Management, atlas-workspace, etc.): this section does not apply — the path-scoped rule won't load there.

## Modes

| Invocation | Behaviour |
|---|---|
| `/bib-validate` | Standard: cross-reference \cite{} ↔ .bib, library check, preprint staleness |
| `/bib-validate --verify-doi` | **Adds DOI resolution**: each `@article`/`@inproceedings` entry gets its DOI checked via `scholarly scholarly-verify-dois`. Bib entries with no DOI or unresolvable DOIs are flagged. Use before submission to catch fabricated/hallucinated entries. |
| `/bib-validate --fix` | Auto-fixes resolvable issues in the project `.bib`; genuinely-missing entries are staged under `.paperpile-import/` with their draft cites marked `\CiteTodo{...}` (build-blocking) for manual Paperpile import. The Paperpile CLI is read-only — it cannot write to the library, so additions are staged, not auto-inserted. |
| Combine: `--verify-doi --fix` | Verify, then fix unverified entries by re-fetching from Crossref |

## When to Use

- Before compiling a final version of a paper
- After adding new citations to check nothing was missed
- When `biber`/`bibtex` reports undefined citations
- As part of a pre-submission checklist (pair with `/proofread`)

## When NOT to Use

- **Finding new references** — use `/literature` for discovery
- **Building a bibliography from scratch** — use `/literature` with `.bib` generation
- **General proofreading** — use `/proofread` (which also flags citation format issues)

## Phase 0: Session Log (Suggested)

Bibliography validation with preprint staleness checks can be context-heavy (OpenAlex lookups, web searches for published versions). Before starting, **suggest** running `/session-log` to capture prior work as a recovery checkpoint. If the user declines, proceed without it.

## Convention

**Default bibliography file is `references.bib`** — this is the standard across all projects (per the `/latex` skill convention). However, the skill also supports:

- Any `.bib` file found in the same directory as the `.tex` files being audited
- Embedded bibliographies using `\begin{thebibliography}` / `\bibitem{key}` blocks
- Both external and embedded simultaneously (rare but possible)

## Bibliography Detection

At the start of validation, detect which bibliography method the project uses:

### 1. External `.bib` file (standard)

Look for `.bib` files in the project directory. Priority order:
1. `references.bib` (preferred — standard naming convention across all projects)
2. Any other `.bib` file in the same directory as the `.tex` files

If **multiple `.bib` files** are found, validate all of them and produce a combined report. Note which file each issue belongs to. If a legacy-named `.bib` file (e.g., `paperpile.bib`) exists alongside `references.bib`, flag it as a potential cleanup opportunity (the project may have migrated from Paperpile).

Full validation applies: cross-reference checks **and** quality checks.

### 2. Embedded `\begin{thebibliography}` / `\bibitem{key}`

Some LaTeX documents define references inline rather than using an external `.bib` file. Detect by scanning `.tex` files for `\begin{thebibliography}`.

Extract keys from `\bibitem` entries:
- `\bibitem{key}` — standard form, key is the argument in braces
- `\bibitem[label]{key}` — optional label form (e.g., `\bibitem[Smith et al., 2020]{smith2020}`), key is in the **second** set of braces

Only **cross-reference checks** apply (missing keys, unused keys, typos). Quality checks (required fields, year, author formatting) are **skipped** because embedded bibliographies don't have structured metadata.

### 3. Both (rare)

If a project has both a `.bib` file and `\begin{thebibliography}` blocks, validate both:
- Run full validation on the `.bib` file
- Run cross-reference checks on `\bibitem` entries
- Merge both key sets when checking for missing citations

## Workflow

1. **Find files**: Locate all `.tex` files in the project
2. **Detect bibliography type**: Check for `.bib` files and/or `\begin{thebibliography}` blocks
3. **Extract citation keys from .tex**: Scan for all citation commands
4. **Extract entry keys from bibliography source(s)**:
   - External: Parse all `@type{key,` entries from `.bib` file(s)
   - Embedded: Parse all `\bibitem{key}` and `\bibitem[label]{key}` entries
5. **Cross-reference**: Compare the two sets
6. **Quality checks**: Validate `.bib` entry completeness (external only)
7. **Produce report**: Write results to stdout (or save if requested)

## Citation Commands to Scan

Scan `.tex` files for all of these patterns:

| Command | Example |
|---------|---------|
| `\cite{key}` | Basic citation |
| `\citet{key}` | Textual: Author (Year) |
| `\citep{key}` | Parenthetical: (Author, Year) |
| `\textcite{key}` | biblatex textual |
| `\autocite{key}` | biblatex auto |
| `\parencite{key}` | biblatex parenthetical |
| `\citeauthor{key}` | Author name only |
| `\citeyear{key}` | Year only |
| `\nocite{key}` | Include in bibliography without in-text citation |

Also handle **multi-key citations**: `\citep{key1, key2, key3}`

## Cross-Reference Checks

### Self-citation handling (double-blind submissions only)

When `--double-blind` is set OR when a `paper-*` directory's vault submission frontmatter shows the venue is double-blind, run a self-citation scan. **Default expectation: the author CAN and SHOULD cite their own prior work — keep the real bib entry and cite it in the third person.** Anonymity comes from removing the author block, not from blinding the bibliography; a `{Anonymous}` entry actually *advertises* the self-citation. See `rules/double-blind-self-citation.md` and `_shared/double-blind-anonymity-checklist.md` §P4–P5.

1. **Load submission author list.** Read `~/vault/submissions/--.md` `authors:` / `coauthors:` field. If absent, prompt: `Submission author surnames (comma-separated):`.
2. **Identify self-citations.** For each `.bib` entry, parse `author = {...}`, tokenize by `and`, extract surnames; mark entries whose authors overlap the submission's as *self-citations* — these are expected, not violations.
3. **Scan the `.tex` body near each self-cite `\cite{}` (±200 chars) for FIRST-PERSON voice** — "our"/"we previously"/"in earlier work of ours". That first-person voice is the actual de-anonymizer, not the names.
4. **Severity:**
   - **Info / no action** — self-citation cited in the third person with the real entry kept. This is the correct finished state. Naming the authors ("[Author] and [Collaborator] [2] show X") in the third person is fine.
   - **Critical** — first-person voice near a self-cite → rewrite to third person (the citation and the real entry stay).
   - **Critical (CFP-conditional)** — *only* if the venue's CFP explicitly requires anonymizing self-citations (some security venues, e.g. CCS) → then also blind the entry. Do **not** blind by default.
5. **Output format (first-person-voice case):**
   ```
   ⚠ FIRST-PERSON SELF-REFERENCE (Critical)
     intro.tex:88  near \cite{smith2026paradox}
       "in our prior work [12] we showed..."
       fix: third person — "Prior work [12] showed..."  (citation + real entry stay)
   ```
   For the CFP-mandated-blinding exception only, additionally anonymize the entry:
   `author = {Anonymized for double-blind review}`, `title = {Title withheld}`, `note = {Anonymized self-citation}`.

This is a **venue-conditional** check, not an unconditional desk-reject gate. Run it with the standard cross-reference checks.

### Critical: Missing Entries

Citation keys used in `.tex` but not defined in the bibliography source (`.bib` file or `\bibitem` entries).

These will cause compilation errors.

### Warning: Unused Entries

Keys defined in the bibliography source but never cited in any `.tex` file.

Not errors, but may indicate:
- Forgotten citations (should they be `\nocite`?)
- Leftover entries from earlier drafts
- Entries intended for a different paper

### Warning: Possible Typos (Fuzzy Match)

For each missing key, check if a similar key exists in the bibliography using edit distance:
- Edit distance = 1: Very likely a typo
- Edit distance = 2: Possibly a typo
- Flag these with the suggested correction

Common typo patterns:
- Year off by one: `smith2020` vs `smith2021`
- Missing/extra letter: `santanna` vs `sant'anna` vs `santana`
- Underscore vs camelCase: `smith_jones` vs `smithjones`

## Reference Manager Cross-Reference

After the disk-based cross-reference, check every `.bib` key against the Paperpile library with ONE dry-run of the canonical resolver:

```bash
python3 "$(cat ~/.config/task-mgmt/path)/scripts/bib/rekey_to_canonical.py" 
```

Produces the full status table (HEALTHY / DRIFT / SUGGESTED / AMBIGUOUS / NOT_FOUND) in ~5s with no per-key CLI calls. Fallback lookups, status semantics, and staleness caveat: [`references/ref-manager-crossref.md`](references/ref-manager-crossref.md)

## Quality Checks on .bib Entries

**These checks apply only to external `.bib` files.** Embedded bibliographies lack structured metadata, so quality checks are skipped for them.

### Required Fields by Entry Type

| Entry Type | Required Fields |
|-----------|----------------|
| `@article` | author, title, journal, year |
| `@book` | author/editor, title, publisher, year |
| `@incollection` | author, title, booktitle, publisher, year |
| `@inproceedings` | author, title, booktitle, year |
| `@techreport` | author, title, institution, year |
| `@unpublished` | author, title, note, year |
| `@phdthesis` | author, title, school, year |

### Year Reasonableness

- Flag entries with year  current year + 1
- Flag entries with no year at all

### Author Formatting

- Check for inconsistent author formats within the file
- **Flag entries where author field contains "and others" or "et al."** — this is never valid in BibTeX. All authors must be listed explicitly. Severity: **Warning**.
- Flag entries with organisation names that might need `{{braces}}` to prevent splitting

### DOI Verification & Fabrication Detection

See [`references/doi-verification.md`](references/doi-verification.md) for hard rules, resolution protocol, and LLM-hallucination detection.

### Preprint Staleness Check

**For every entry that looks like a preprint**, check whether a peer-reviewed version has since been published. Full detection signals, lookup protocol, and classification: [`references/preprint-check.md`](references/preprint-check.md)

## Severity Levels

| Level | Meaning |
|-------|---------|
| **Critical** | Missing entry for a cited key — will cause compilation error |
| **Warning** | Unused entry, possible typo, missing required field |
| **Info** | Year oddity, formatting suggestion, bibliography type note |

## Bibliography Output

After validation, offer these actions if applicable:

- **Embedded bibliography → offer to create `references.bib`**: If the project uses `\begin{thebibliography}`, offer to extract the references into a proper `references.bib` file (one `@misc` entry per `\bibitem`, with the full text as a `note` field). The author can then enrich the entries with proper metadata.
- **Non-standard `.bib` name → offer to rename**: If the existing `.bib` file is not named `references.bib`, offer to rename it to `references.bib` and update the `\bibliography{}` command in the `.tex` file.

These are **offers only** — do not make changes without explicit confirmation.

## Report Format

Full report template with all sections: [`references/report-template.md`](references/report-template.md)

Sections: Summary table → Critical (missing entries) → Warning (typos, unused, missing fields, DOI mismatches, stale preprints) → Info (year issues) → Limitations (for embedded bibliographies).

## Optional: Metadata Verification

See [`references/metadata-verification.md`](references/metadata-verification.md) for Paperpile and scholarly CLI lookup workflows.

## Deep Verification Mode (Parallel, Disk-Based)

See [`references/deep-verify-protocol.md`](references/deep-verify-protocol.md) for auto-trigger thresholds (≥40 entries) and sub-agent architecture.

## Council Mode (Optional)

For high-stakes submissions. Trigger: "council bib-validate", "thorough bib check". Full details: [`references/council-mode.md`](references/council-mode.md)

## Fix Mode

After producing the validation report, automatically fix resolvable issues. **DRIFT (paper in library under a different key) → the verified rekey chain:** `rekey_to_canonical.py --apply` (remaps `\cite` keys in `.tex`; `--extra-map` for confirmed SUGGESTED/AMBIGUOUS cases) → `rebuild_paperpile_bib.py ` (regenerates the `.bib` from canonical Paperpile exports) → `citation_lint.py` → `latexmk` compile check. NOT_FOUND → search, then stage the entry as a `.bib` under `.paperpile-import/` and replace its draft cite with `\CiteTodo{slug}{title; authors; year; DOI}` (build-blocking until imported); metadata → correct BibTeX. Library additions are *staged* under `.paperpile-import/` for manual import — the Paperpile CLI is read-only (no import command; `paperpile write-bib --citekeys` only exports entries already in the library).

Full auto-fix actions, post-fix maintenance, and skip conditions: [`references/fix-mode.md`](references/fix-mode.md)

## Quality Scoring

When producing a full validation report, apply numeric quality scoring using the shared framework:

- **Framework:** [`../shared/quality-scoring.md`](../shared/quality-scoring.md) — severity tiers, thresholds, verdict rules

Map validation findings to the framework tiers:
- **Critical** (-15 to -25): Missing entry for a cited key (compilation error)
- **Major** (-5 to -14): DOI mismatch, **likely fabricated reference** (LLM-drafted hallucination), stale preprint with published version available, "et al." in author field
- **Minor** (-1 to -4): Missing optional fields, year oddities, unused entries

Compute the score and include the Score Block in the report after the summary table.

## Log to REVIEW-STATE.md (final step)

Write the bib-validate report to `reviews//bib-validate/.md` (where `` is the paper directory slug, e.g., `paper-jtp`, `paper-philtech`; create `mkdir -p reviews//bib-validate/` first). Then append a row to the project's `REVIEW-STATE.md`:

```bash
bash ~/.claude/skills/_shared/review-state-log.sh \
  --check bib-validate \
  --paper "" \
  --verdict "" \
  --score "" \
  --open-issues "/" \
  --report "reviews//bib-validate/.md" \
  --notes "" \
  [--trigger "pre-submission-report|review-cluster"]
```

- Verdict: PASS if no missing/unused/typo'd citations; ISSUES FOUND otherwise.
- Score: the numeric quality score if computed; `—` otherwise.
- Open issues: total of (missing + unused + typo'd) at

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [flonat](https://github.com/flonat)
- **Source:** [flonat/flonat-research](https://github.com/flonat/flonat-research)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-flonat-flonat-research-bib-validate
- Seller: https://agentstack.voostack.com/s/flonat
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.