manage-refs

Manage-Refs Skill

You are routing reference-handling work for a medical manuscript. The user is somewhere in the lifecycle — drafting, building a circulation DOCX, swapping CSL after a journal rejection, fixing a cross-reference defect surfaced by QC, or wiring up live Zotero field codes for a co-author Word workflow. Pick the right tool from the decision table; do not invent a parallel pipeline.

Why This Skill Exists

Reference handling spans every late-stage skill: /write-paper builds the first DOCX, /revise rebuilds it after each reviewer round, /peer-review emits a critique that quotes references back, /sync-submission packages the final tarball, /find-journal informs CSL swaps on rejection cascade, and /verify-refs audits the bibliography. Until 2026-05-01 these scripts lived under skills/write-paper/scripts/, which made /revise and /sync-submission silently depend on a sibling skill — a layering inversion that broke when /write-paper was loaded into a non-research project. Moving the lifecycle tools here turns reference handling into a first-class concern with one decision tree, one set of CSL files, and one provenance file (NOTICE.md) for the vendored Zotero CWYW writer.

Validated 2026-05-01 against a 21-reference meta-analysis manuscript (a meta-analysis project's submission) for both pandoc-citeproc and Zotero-CWYW paths.

Anti-Hallucination Guarantees

1. Citekey discipline (Phase 0): every in-text citation must be

[@bibkey] resolvable in refs.bib. scripts/check_citation_keys.py is a hard gate — UNDEFINED keys exit non-zero and block the build.

[@NEW:topic] placeholder convention: while drafting, /write-paper may emit [@NEW:topic_slug] markers for citations the author still needs to source. check_citation_keys.py classifies these as NEW_PLACEHOLDER (not UNDEFINED) and exits 0 — the build is allowed to proceed during drafting. Phase 7.6 (DOCX render) is a hard gate: zero NEW_PLACEHOLDER entries must remain. Resolve each by adding the citation to Zotero (then /lit-sync refreshes refs.bib) and replacing the placeholder with the real [@bibkey]. Never let a [@NEW:...] reach a rendered DOCX.

1. No hand-typed References list — references are always rendered by

pandoc citeproc + journal CSL or by the Zotero Word plugin (CWYW). See ~/.claude/rules/manuscript-references.md.

1. Zotero metadata is never invented — inject_zotero_cwyw.py fetches

item data live from http://localhost:23119. Any HTTP failure aborts with a non-zero exit so partial bibliographies never reach the user.

1. Marker conversion is mapping-driven — md_marker_convert.py will

never guess a Zotero key for a number; unmapped markers stay as [N] and are reported on stderr.

1. Cross-reference QC is a submission gate — scripts/check_xref.py

--strict exits 1 on any MISSING_DOCX / MISSING_BODY / MISMATCH, blocking pipelines that try to ship a DOCX whose Table/Figure citations don't match captions.

1. Audit boundary: this skill writes; bibliographic correctness against

PubMed/CrossRef stays in /verify-refs. Always invoke /verify-refs after a render before signing off — one read-only audit, one writer.

Decision Tree

| Situation | Tool | Why | |---|---|---| | Validate [@bibkey] ↔ refs.bib (UNDEFINED / UNUSED keys) | scripts/check_citation_keys.py | Hard build gate, runs in seconds | | Single-author submission lockdown, frozen output | scripts/render_pandoc.sh -j <journal> | Reproducible, CI-friendly | | Cascade rejection (e.g., ER → JVIR → CVIR) | render_pandoc.sh with new -j | CSL swap reformats references in seconds | | Reviewer revision: add 1–2 refs to a Word doc with co-authors live | Zotero Word plugin (user GUI) | Minimal disruption to track-changes flow | | Reviewer revision: bulk reference change | Edit markdown SSOT, re-run render_pandoc.sh | Consistency, no cherry-pick risk | | Migrate [N] numeric markers → [@key] for pandoc | scripts/md_marker_convert.py --to-keys | Mapping-driven, partial conversion safe | | Convert [@key] → [N] for round-trip / debug | scripts/md_marker_convert.py --to-numbers | Same map, opposite direction | | Wire native Zotero CWYW field codes into a .docx (live Refresh in Word) | scripts/inject_zotero_cwyw.py | Co-author Word workflow, post-circulation editability | | Manuscript ↔ rendered DOCX cross-reference QC | scripts/check_xref.py --strict | Submission gate (P0 blocker on mismatch) | | Figures/tables submitted as separate attachments (radiology, most medical journals) | check_xref.py --strict --allow-separate-attachments | Downgrades MISSING_DOCX to WARN; MISSING_BODY/MISMATCH remain P0 | | v_(N+1) docx build-time regeneration check | check_xref.py --vN-docx-md5 <prev>.docx [--vN-md <prev>.md] | Defense-in-depth: identity = unmodified seed copy; missing diff lines = body not regenerated | | Master pre-submission gate (recommended before any submission) | scripts/pre_submission_gate.sh | Chains check_citation_keys → verify_refs --strict → render_pandoc (optional) → check_xref --strict; single artifact qc/pre_submission_gate.json | | Bibliographic audit against PubMed / CrossRef | delegate to /verify-refs | Audit-only — keep writer/auditor separation |

Workflows

A. Pandoc citeproc (default for solo authors and final submissions)

User provides manuscript.md with [@bibkey] citations + refs.bib.

1. Gate: python "${CLAUDE_SKILL_DIR}/scripts/check_citation_keys.py" manuscript.md refs.bib

— exits non-zero on UNDEFINED keys. Fix and re-run.

1. Render:

``bash "${CLAUDE_SKILL_DIR}/scripts/render_pandoc.sh" \ -j european-radiology \ -i manuscript.md \ -b refs.bib \ -o manuscript_final.docx ` Bundled CSLs (in citation_styles/): european-radiology, radiology, american-journal-of-roentgenology, cardiovascular-and-interventional-radiology, korean-journal-of-radiology, vancouver, vancouver-superscript, springer-basic-brackets, springer-vancouver-brackets. Use radiology for RYAI; use vancouver` for JVIR (no dedicated CSL).

1. QC:

``bash python3 "${CLAUDE_SKILL_DIR}/scripts/check_xref.py" \ --md manuscript.md --docx manuscript_final.docx \ --out qc/xref_audit.json --strict ` Treat submission_safe: false as a halt. Route fixes by symptom — see the table in references/check_xref_symptoms.md`.

1. Audit hand-off: invoke /verify-refs for the PubMed/CrossRef audit

before sign-off.

B. Zotero CWYW (co-author Word workflow)

User has a markdown SSOT and wants reviewers to edit citations directly in Word. Each reference must already exist as a Zotero item; the user supplies a [N] → ZoteroKey mapping.

1. Convert markers:

``bash python3 "${CLAUDE_SKILL_DIR}/scripts/md_marker_convert.py" \ --input manuscript.md --output manuscript_keys.md \ --map ref_map.json --to-keys ` Optionally stage with --active-ns 1,2,3,4,19` for a sample build first (validated on an active meta-analysis project: 5-ref sample reduces Word Refresh blast radius when debugging).

1. Render to .docx with pandoc (workflow A) so the body has plain text

[@key] markers, OR pre-build a .docx some other way that still contains plain [@key] text.

1. Inject CWYW:

``bash python3 "${CLAUDE_SKILL_DIR}/scripts/inject_zotero_cwyw.py" \ --input manuscript_keys.docx --output manuscript_cwyw.docx \ --user-id 16613550 --keys-from keys.txt `` The script fetches Zotero metadata via the local connector (port 23119); any HTTP failure aborts with non-zero exit.

1. First-build instruction (REQUIRED — see Known Limitation #1): open

the output in Word → Zotero tab → Add/Edit Bibliography once. After that, Refresh keeps citations and bibliography in sync as a