manage-latex-bibliography

Manage LaTeX Bibliography

Workflow

1. Infer the operation from the request and available files:

   • Scan checks .tex files against the bibliography for missing keys.
   • Audit checks the bibliography against the reference PDF directory.
   • Initialize runs audit --all to verify every bibliography entry; use it only when the user explicitly requests initial or full verification.
   • Verify existing checks existing entries against Crossref for DOI, title, and year drift.

   To revise a single entry, edit its object in the generated proposal JSON directly, then re-run validate.

   When the request clearly identifies one operation, proceed without asking. Ask one concise clarification only when the operation or required scope cannot be inferred.

2. Confirm only the inputs required for that operation: the project root, main .tex file, references.bib, reference PDF directory, or proposal file.

3. Locate this skill directory and assign its absolute path to SKILL_DIR.

4. Run the inferred operation without modifying the project:

   Scan:

   python "$SKILL_DIR/scripts/manage_bibliography.py" scan \
     --project /path/to/project \
     --output /path/to/project/bibliography-proposal.json
   

   Initialize:

   python "$SKILL_DIR/scripts/manage_bibliography.py" audit \
     --bib /path/to/project/references.bib \
     --pdf-dir /path/to/project/references \
     --output /path/to/project/bibliography-proposal.json \
     --all
   

   Audit:

   python "$SKILL_DIR/scripts/manage_bibliography.py" audit \
     --bib /path/to/project/references.bib \
     --pdf-dir /path/to/project/references \
     --output /path/to/project/bibliography-proposal.json
   

   Verify existing:

   python "$SKILL_DIR/scripts/manage_bibliography.py" verify-existing \
     --bib /path/to/project/references.bib \
     --output /path/to/project/bibliography-verify-report.json
   

   The report lists each entry with verified, inconsistent, unverified, or skipped status. If Crossref is unreachable, entries gracefully degrade to unverified so the workflow does not crash.

5. Review missing citation keys and inspect prose for likely uncited works. Never treat a citation key or prose mention as proof of publication identity.

6. Research each candidate according to references/verification-rules.md. Use any available skill that provides the literature-search capability (e.g., literature-search-repec, literature-search-openalex) to retrieve the ground-truth metadata. If no such skill is installed, fall back to the verify-existing Crossref path or tag the entry [UNVERIFIED] and notify the user rather than fabricating metadata. See docs/architecture-dependencies.md for the graceful-degradation contract.

7. Give each candidate and its evidence to an independent subagent for a fresh online check. If subagents are unavailable, perform a separate second lookup without relying on first-pass conclusions.

8. Format titles according to references/title-case-rules.md.

9. Populate each proposal entry with its BibTeX type, fields, source URLs, conflicts, verifier identity, and status. Use verified only after the independent check succeeds.

10. Ask the user to approve every prose-inferred reference and every correction to an existing entry. Corrections must include the existing fields as before_fields, use approved status, and set both approval flags to true.

11. Validate the completed proposal:

    python "$SKILL_DIR/scripts/manage_bibliography.py" validate \
      --proposal /path/to/project/bibliography-proposal.json
    

12. Apply only after validation succeeds:

    python "$SKILL_DIR/scripts/manage_bibliography.py" apply \
      --proposal /path/to/project/bibliography-proposal.json
    

13. Review bibliography-apply-result.json and compile the project when a TeX toolchain is available.

Re-run scan whenever a tracked .tex or .bib file changes.

Entry Rules

Use lowercase authorYearFirstTitleWord citation keys, for example acemoglu2001colonial. Skip title stop words. If the key collides with another work, append the next meaningful title word; do not add an arbitrary numeric suffix.

Use lowercase BibTeX field names and string field values. Keep braces balanced and protect case-sensitive title content before validation.

Inferred References

The agent may identify author-year mentions, titles, DOI strings, or other clear publication references in prose. Show the source passage and proposed publication to the user. Do not add the citation or entry until the user approves it.

AEA Style

This skill does not distribute aea.bst. For a traditional BibTeX project, ask the user before downloading the official AEA template. After confirmation:

python "$SKILL_DIR/scripts/manage_bibliography.py" install-aea-style \
  --project /path/to/project \
  --confirm-download

The helper accepts only an HTTPS download that ends on the official aeaweb.org host and records its URL, retrieval time, and SHA-256 digest. Never use an unofficial mirror.

Preserve an existing bibliography style. For biblatex or biber, maintain entries but do not activate aea.bst or convert the project.

Safety Rules

• Never invent bibliographic metadata.
• Never apply unresolved or unverified entries.
• Never apply inferred references or existing-entry corrections without user approval.
• Do not bypass duplicate identifier, stale digest, project containment, archive, or overwrite failures.
• Do not add aea.bst or downloaded AEA files to this skill or repository.