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.

2. 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.

3. 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.

4. 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.

5. 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.

6. 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

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.
2. Render:

   "${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).
3. QC:

   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.
4. 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:

   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).
2. 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.
3. Inject CWYW:

   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.
4. 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