Bib Audit

---
name: bib-audit
description: >-
  Use when the user asks to audit a bibliography or apply corrections identified by a bibliography audit. Do not use for general LaTeX citation editing.
---

<!-- BEGIN BLUEPRINT INTERFACES -->
> Generated from `blueprint.yaml`. Do not edit this block by hand.

Executable Interfaces:

Call `famulus.invoke` with required `caller` (caller skill), `interface`, `version`, and `arguments`; optional `dry_run` defaults to false. Compact uses ordered `positionals` plus an option mapping; ordered raw argv uses `positionals: []` plus every argv token in list `options`. Never mix forms.
- `bib-audit._rtx.interface.scripts-bib-similarity` — Detect duplicate and version-pair candidates in a .bib file by scoring all entry pairs.
  - Caller: `bib-audit`
  - Version: 1
  - Alternative: `owner`
    Arguments JSON (replace labels with actual values). Omit optional positionals and options that are not needed.
    {"options": {"--threshold": "0.3"}, "positionals": ["file.bib"], "stdin": null}
    Required options: []; positional arity: 1..1; stdin: forbidden
- `bib-audit._rtx.interface.scripts-bib-validate-bibtex` — Validate a BibTeX/natbib .bib file for syntax errors and missing required fields (not for biblatex projects).
  - Caller: `bib-audit`
  - Version: 1
  - Alternative: `owner`
    Arguments JSON (replace labels with actual values). Omit optional positionals and options that are not needed.
    {"options": {}, "positionals": ["file.bib"], "stdin": null}
    Required options: []; positional arity: 1..1; stdin: forbidden

Instruction Interfaces:

These are LLM-readable instruction surfaces. Read and follow them directly; do not invoke the MCP server for them.
- `setup-python-environment.interface.repair-selected-packages@1` — Repair the core or one caller-owned package declaration in the exact selected Python environment without MCP.
<!-- END BLUEPRINT INTERFACES -->
# Bibliography Audit

Conservative bibliography auditor. Default behavior: produce a structured report. Apply transformations only on explicit user approval.

Before validating or comparing bibliography entries, follow
`setup-python-environment.interface.repair-selected-packages` for this owner's exact
declaration `["bibtexparser"]`. Complete the full Task 2 fingerprint procedure; on any
failure, stop before invoking either bibliography interface.

## Invocation

Ask for:
1. The `.bib` file (required).
2. Accompanying `.tex` project files (optional; enables backend inference and project-aware citation rewrites).
3. House style preferences (optional).

**Backend inference** — when `.tex` files are provided, scan the preamble and infer the backend before proceeding:

| Signal (in preamble) | Backend |
|---|---|
| `\usepackage{biblatex}` or `\usepackage[...]{biblatex}` | biblatex + Biber |
| `\addbibresource{...}` (without explicit `\usepackage{biblatex}`) | biblatex + Biber |
| `\usepackage{natbib}` | BibTeX + natbib |
| `\bibliographystyle{...}` + no natbib/biblatex package | BibTeX (plain) |

If multiple `.tex` files are provided, check the root/main file first. If signals conflict or are absent, ask the user. If no `.tex` files are provided, ask the user for the backend directly.

## Global rules

- **Reports before transformations.** Default behavior is a report with suggested actions, no file edits.
- **Optional steps require explicit user approval.** Never perform citation-key standardization, aggressive formatting, duplicate merging, or project-wide rewrites without approval.
- **Citation-key changes are project-aware when `.tex` files are provided.**
  - `old → new`: update all `\cite{old}` → `\cite{new}`.
  - Merged `y → x`: replace `y` citations with `x`; deduplicate citation commands.
  - Entry deleted without replacement: check for citations, ask before proceeding.
- **Do not infer destructive changes from missing information.** If a tool report lacks a clear replacement or merge target, ask or leave for manual review.
- **Warn before key changes when no `.tex` files are provided.**

## Workflow

### Step 1 — Local validity and formatting

#### biblatex + Biber

```
biber --tool --validate-datamodel <file.bib>
```

Produces `<basename>_bibertool.bib` (normalized output) and `<basename>.blg` (log). Parse the `.blg` log; map `ERROR`/`WARN`/`INFO` prefixes directly to the audit classification.

**1a.** Report all log entries: duplicate keys, missing required fields (biblatex spec), malformed entries, unknown fields, malformed author/DOI/year/page fields.

**1b.** Diff original `.bib` against `<basename>_bibertool.bib`. Report differences in field ordering, field-name casing, indentation, page-range dashes, title capitalization, author/journal/publisher formatting, DOI/URL/arXiv formatting, citation-key style. Infer dominant style from the file; do not impose a universal one.

---

#### BibTeX + natbib

Do not run `biber --tool` — it uses biblatex field names (`journaltitle`, `date`) and will spuriously flag valid BibTeX fields (`journal`, `year`).

Use `scripts-bib-validate-bibtex` to validate the file. Output is JSON. Read `parse_errors` first (file-level failures), then `entries[*].issues`. Each issue has `level` (ERROR/WARNING/INFO), `field`, and `message`.

**1a.** Report all ERRORs and WARNINGs. Required fields are checked against the BibTeX spec (e.g. `@article` needs `author`, `title`, `journal`, `year` — not `journaltitle`/`date`).

**1b.** No normalized reference output is available. Read the file directly and report style inconsistencies: field-name casing (BibTeX convention: lowercase), field ordering within entries, indentation and spacing, page-range dashes, title brace-protection, citation-key style.

---

**Optional — citation-key standardization** (both backends)**:** Offer four choices: (1) preserve existing keys, (2) report inconsistencies only, (3) standardize `.bib` only, (4) standardize `.bib` and update `.tex`. Warn if no `.tex` files are provided.

---

### Step 2 — External metadata verification (bibtex-check)

Install via `pip install bibtex-updater`. Run:

```
bibtex-check <file.bib> --report report.json --non-generative --mailto <your-email> --verbose
```

- `--non-generative` disables LLM calls; use it for reproducibility and policy compliance.
- `--mailto` registers a contact address with CrossRef/OpenAlex polite pools; improves rate limits.
- `--skip-books`, `--skip-working-papers` skip entry types that rarely resolve externally.
- If the tool fails or times out on an entry, mark it `UNVERIFIED` and continue; note which entries could not be checked.

Per-entry: read `status` (see mapping below), `field_comparisons` (has `entry_value`/`api_value`/`similarity_score`/`matches` per field), and `best_match.doi` (for Step 3 cross-reference). Top-level `summary` has aggregate counts.

Map `status` to audit classification:

| Tool status | Audit classification |
|---|---|
| `verified` | VERIFIED |
| `partial_match` | PROBABLE MATCH |
| `not_found`, `unconfirmed`, `preprint_only` | UNVERIFIED |
| `title_mismatch`, `author_mismatch`, `year_mismatch`, `venue_mismatch`, `arxiv_id_mismatch`, `doi_mismatch`, `hallucinated` | CONFLICT |
| `doi_not_found` | CONFLICT — DOI is present but does not resolve; likely fabricated or mistyped |
| `published_version_exists` | UNVERIFIED — flag for Step 3 (a published version was found; use `bibtex-update` to upgrade). Note: bibtex-check may instead return `verified` for a preprint that resolves via arXiv even when a published version exists — the similarity script may catch such version pairs that this status misses. |
| `api_error` | UNVERIFIED — note that lookup failed |

Do not treat UNVERIFIED as fake. Books, unpublished manuscripts, lecture notes, older works, and private drafts may be real even when no external match is found.

---

### Step 3 — Duplicate and version audit

Use `scripts-bib-similarity` to get a ranked candidate list. Output JSON: each pair has `score` (0–1), `confidence` (EXACT/HIGH/MEDIUM/LOW), and per-field signals (`doi`/`eprint`/`isbn` identifier match, `title`/`author`/`year`/`venue` soft scores). `EXACT` = shared identifier; treat as definite duplicate. Threshold 0.3 is loose by design — use the list as a checklist, not a verdict.

Known limitation: arXiv IDs in `howpublished`/`note`/`url` free text are extracted as a fallback, but prefer `eprint` field for reliable identifier matching.

Cross-check with Step 2: if two entries share the same `best_match.doi`, treat them as EXACT regardless of what the script reported. Skip entries with status `not_found` or `unconfirmed` when doing this cross-check — their `best_match.doi` may be a spurious near-hit, not a confirmed match. Flag any entry with `published_version_exists` status as a version-pair candidate.

For each candidate pair (or group), determine the relationship:
- **exact duplicate** — identical or near-identical entries, same work, no meaningful difference
- **likely duplicate** — same work, minor metadata differences
- **version pair** — same work, different publication stages (preprint/journal, conference/journal, draft/final)
- **uncertain** — insufficient evidence; flag for manual review

For each duplicate/version group, report: grouped entries, relationship type, proposed canonical entry, proposed action, evidence (script score + signals, identifier match, bibtex-check cross-reference).

Default canonical preference: journal article > conference/proceedings > accepted/forthcoming with final metadata > latest preprint > older draft. Preserve non-canonical versions when content, author list, or title differ, or when there is a plausible reason to cite them separately.

**Optional — merge or delete entries.** If merging `y → x`: keep `x`, delete `y`, record the merge, update `.tex` citations, deduplicate citation commands. If deleting without replacement and `.tex` files exist: check for citations and ask what to do. If no `.tex` files were provided, warn the user explicitly that the deletion or key change may silently break citations in any accompanying `.tex` files. Do not infer a merge target destructively from incomplete information.

---

## Modification layer

Invoke only when the user approves specific transformations. Never for audit-only steps.

**Safe transformations** (low-risk; may be approved in a single batch):
- normalize whitespace and indentation;
- sort fields within entries;
- remove exact duplicate fields;
- normalize DOI, page-range dash, URL/arXiv field formatting;
- apply consistent field ordering;
- remove empty fields.

Safe transformations may be approved in bulk; produce a single combined diff before writing.

**Review-required transformations** (each requires individual approval):
- change titles, authors, years, venues;
- add missing publication metadata;
- replace working-paper with published-version metadata (use `bibtex-update` — see below);
- delete or merge entries (use `bibtex-update --dedupe` for DOI/title-based deduplication);
- change citation keys;
- aggressive house-style rewrites.

**`bibtex-update`** for preprint upgrades and deduplication. Always preview first (`--dry-run` requires `-o` even in preview mode). Review these side effects before approving — flag each to the user:
- Author names may be reformatted from Last-First to First-Last.
- `eprint` fields may be silently dropped.
- Titles may gain trailing punctuation or changed capitalisation from the API.
- Top-of-file comment blocks are stripped from the output.
- New page ranges introduced by upgrades may use single hyphens rather than en-dashes.
- **Do not run `--dedupe` on a file that contains both exact duplicates and version pairs without careful preview.** The combination can produce hybrid entries with contradictory fields (e.g. `@article` with simultaneous `journal`, `booktitle`, and `howpublished`). Run deduplication only after resolving version pairs separately, or review the output entry-by-entry before writing.
```
bibtex-update <file.bib> --dry-run --verbose -o /tmp/preview.bib
bibtex-update <file.bib> [--dedupe] [--fill-fields] -o updated.bib --report changes.jsonl
```

**Project-aware transformations** (only when `.tex` files provided):
- update citation keys in `.tex` files;
- replace citations to merged entries;
- deduplicate keys within `\cite{…}` commands;
- verify citation consistency after changes.

Rewrites apply to any citation command of the form `\CMDNAME[...]{keys}` — including all natbib variants (`\citep`, `\citet`, `\citealt`, `\citealp`, `\citeauthor`, `\citeyear`) — not only `\cite`. Optional arguments `[post]` and `[pre][post]` are preserved unchanged. Examples for `y → x`:

```latex
\cite{y}        →  \cite{x}
\cite{a,y,z}    →  \cite{a,x,z}
\cite{x,y,z}    →  \cite{x,z}      ← deduplicate; never \cite{x,x,z}
```

---

## Output

Default audit report structure:
1. Summary
2. Critical errors
3. Local validity and formatting issues
4. External verification results
5. Duplicate/version groups
6. Suggested actions
7. Optional transformations available

**Summary section contents:** total entries parsed; ERROR / WARNING / INFO counts from Step 1; verification counts from Step 2 (VERIFIED N/total, CONFLICT N, UNVERIFIED N, api_error N); duplicate candidate pairs by confidence (EXACT N, HIGH N, MEDIUM N, LOW N); count of entries with `published_version_exists`.

Per-issue: entry key, issue type, severity, explanation, suggested action, evidence source, action class (automatic / approval-required / manual).

**Suggested actions** — always conclude the report with a numbered list of concrete next steps, ordered by priority (errors and conflicts first, then duplicates, then style). Each item should be actionable in one step and specify the entry key(s) involved. Example:

```
## Suggested Actions
1. Fix missing `journal` field in smith2020 [ERROR — manual]
2. Resolve DOI conflict in jones2019: API reports doi:10.1234/x, file has doi:10.9999/y [CONFLICT — manual]
3. Merge chen2021 → chen2022 (preprint superseded by journal article) [approval required]
4. Upgrade nguyen2020 to published version via bibtex-update [approval required]
5. Apply safe formatting fixes (whitespace, page-range dashes) across all entries [batch-approvable]
```

After transformations: cleaned `.bib`, diff, change log, key-renaming map (if keys changed), merge map (if entries merged), modified `.tex` files (if project-aware).

### Minimal example

```
## Summary
Entries: 47 | Errors: 2 | Warnings: 8 | Verified: 31/47 | Duplicate candidates: 3 pairs

## Critical errors
- smith2020 (@article): missing required field `journal`. [ERROR, manual]

## Duplicate/version groups
Group 1 — version pair (HIGH, score 0.83)
  chen2021 (@misc, arXiv preprint) ↔ chen2022 (@article, Journal of ML)
  Evidence: identical title tokens, identical authors, year diff 1 (score 0.82), no shared identifier
  Canonical: chen2022 (published journal article)
  Proposed action: merge chen2021 → chen2022 [approval required]
```