manage-refs

# Manage-Refs Skill

> **Canonical source (issue #16).** This SKILL.md is the single canonical
> reference for the reference-*workflow* (validate keys → render CSL → convert
> markers → QC cross-references → inject Zotero CWYW). Audit-only bib
> verification is owned by `skills/verify-refs/SKILL.md`. Any user-scope rule or
> external note about reference handling should point here (workflow) or to
> verify-refs (audit) rather than restating the "how", to prevent drift.

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. `--allow-separate-attachments` downgrades the two
   rows a separate-attachment submission legitimately produces; it never
   downgrades a `MISSING_BODY` whose float IS in the rendered DOCX.
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

| 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 |
| Verify a journal CSL renders the in-text format / DOI / journal-name style the author guide actually requires | `scripts/check_csl_render.py --csl <x>.csl --bib refs.bib --journal <key>` | A stub/"dependent" CSL inherits its parent's format, which may differ from the guide (parenthetical vs superscript, DOI kept, full journal names). Run BEFORE submission, not after the proof PDF |
| Reference list prints FULL journal names but the journal wants NLM abbreviations | `scripts/fill_journal_abbrev.py` | Resolves each entry DOI → PMID → PubMed NLM `shortjournal` into the `.bib` so CSL `form="short"` renders abbreviations; authoritative source, never invents abbreviations |
| 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 --str