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
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.
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.
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.
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.
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.
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 --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 |
| Duplicate bibliography in the built artifact |
scripts/check_reference_duplication.py --docx <built>.docx (or --text <rendered>.md) |
Fires when the reference list is duplicated — DUP_REF_HEADING / REF_NUMBER_RESTART / REF_SIGNATURE_DUP (Major). Catches the hybrid hand-typed ## References list + pandoc --citeproc auto-bibliography, which renders two lists (the second often after the legends). Run after any citeproc build |
Publisher markup in a .bib title (renders as garbage) |
scripts/check_bib_title_markup.py --bib refs.bib --strict |
CrossRef ships <scp>WHO</scp> / <i>IDH</i> in titles and a DOI-add stores them verbatim; BBT then escapes them ({$<$}scp{$>$}) or strips them without restoring the space (andTERTPromoter, 1p/19q,IDH). verify_refs proves the reference is true; this proves it will print. TITLE_MARKUP / TITLE_FUSION (Major) |
| Master pre-submission gate (recommended before any submission) |
scripts/pre_submission_gate.sh |
Chains check_citation_keys → check_bib_title_markup → verify_refs --strict → render_pandoc (optional) → check_xref --strict; single artifact qc/pre_submission_gate.json |
| Direct render with a built-in reference audit |
scripts/render_pandoc.sh (audits the .bib via /verify-refs first; blocks on FABRICATED/MISMATCH/duplicates) |
Defense-in-depth so even a direct render call cannot ship hallucinated citations; best-effort (skips with a warning if /verify-refs is not alongside), opt out with -S. The master gate passes -S since it audits in stage 2 |
| 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.
- Gate:
python "${CLAUDE_SKILL_DIR}/scripts/check_citation_keys.py" manuscript.md refs.bib
— exits non-zero on UNDEFINED keys. Fix and re-run.
- Render:
"${CLAUDE_SKILL_DIR}/scripts/render_pandoc.sh" \
-j european-radiology \
-i manuscript.md \
-b refs.bib \
-o manuscript_final.docx
For the current inventory and what each style renders, read
citation_styles/README.md — that table is the registry. render_pandoc.sh also lists
what is on disk when -j names a style it cannot find, so ask the script rather than
trusting a list written here. Two standing fallbacks: use radiology for RYAI and
vancouver for JVIR (neither has a dedicated CSL).
- 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.
- 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.
- 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).
- 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.
- 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.
- 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 authors
edit.
- Surgical patches are unsafe: for ref additions in later rounds, edit
the markdown SSOT and rebuild the whole .docx instead of regex-patching
the post-CWYW file. Zotero's rendered
[N] superscripts can collide
with plain [N] markers and corrupt the field codes.
C. Cascade rejection re-render (find-journal hand-off)
User got rejected from journal A and /find-journal recommended journal B.
- Confirm the new CSL exists in
citation_styles/ (or fetch from
https://citationstyles.org/styles and drop in).
- Re-run
render_pandoc.sh -j <new-csl> against the same manuscript.md +
refs.bib.
- Re-run
check_xref.py --strict.
- Re-run
/verify-refs if any new references were added during the
inter-journal revision.
D. Cross-reference QC only
User shipped a manuscript and a reviewer flagged a Table/Figure mismatch.
Run check_xref.py --strict on the current manuscript.md + .docx.
Inspect qc/xref_audit.json. Body caption is the SSOT — fix manuscript.md
and rebuild, never patch the .docx by hand.
See references/check_xref_symptoms.md for the
MISSING_BODY / MISSING_DOCX / MISMATCH triage table.
For journals that accept figures and tables as separate attachment files
(the default in European Radiology, Radiology, AJR, JVIR, KJR, and most
medical journals), pass --allow-separate-attachments. It downgrades two
rows, and the run reports them apart because their evidence differs:
MISSING_DOCX — a --docx was supplied and proved the float is not in
the rendered main document. That is what a separate attachment looks like.
MISSING_BODY with no --docx supplied — nothing was checked. The float
is either separately attached, as you declared, or a caption nobody wrote.
Excused on your word, printed as EXCUSED WITHOUT EVIDENCE, and counted in
summary.downgraded_unchecked.
MISMATCH stays P0. So does MISSING_BODY when the float is in the
rendered DOCX — that is SSOT drift, and no attachment policy makes the build
pipeline an acceptable single source of truth for a caption.
Run once with --docx before submitting. The flag is a declaration, not a
verification; supplying the DOCX is what converts an excuse into evidence.
D'. v_(N+1) docx regeneration check (build-time companion)
When building v_(N+1) from a frozen v_N, the v_(N+1) docx MUST differ
from v_N docx by content — a byte-identical copy is a silent seed-copy
that will revert markdown edits at peer review. check_xref.py carries
two flags for the build-time companion to the submission-time gate
in scripts/verify_package_integrity.py --assert-vN-docx-changed:
python3 "${CLAUDE_SKILL_DIR}/scripts/check_xref.py" \
--md manuscript_v2.md \
--docx manuscript_v2.docx \
--vN-docx-md5 manuscript_v1.docx \
--vN-md manuscript_v1.md \
--strict
--vN-docx-md5 alone: MD5 identity check. Identical bytes = FAIL.
--vN-docx-md5 + --vN-md: additionally extracts the markdown-only diff
between v_N and v_(N+1) and verifies each ≥40-char diff line appears
verbatim (whitespace-normalized, case-insensitive) in the new docx
body XML. Missing diff lines = body did not pick up the markdown edits.
Output records the result under vN_docx_check in qc/xref_audit.json.
Either failure mode causes a non-zero exit even without --strict.
E. Master pre-submission gate (recommended end-to-end chain)
The single entry point that combines workflows A and D plus /verify-refs
into one aborting chain. Use this immediately before submission or before
circulating a v_N package to senior co-authors.
bash "${CLAUDE_SKILL_DIR}/scripts/pre_submission_gate.sh" \
--md manuscript/manuscript.md \
--bib manuscript/_src/refs.bib \
--docx submission/<journal>/manuscript.docx \
--allow-separate-attachments # omit if the journal accepts inline figures/tables
Stage order (first failure aborts):
check_citation_keys.py manuscript.md refs.bib — UNDEFINED / UNUSED keys
verify_refs.py refs.bib --strict — PubMed / CrossRef per-entry verification
render_pandoc.sh -j <csl> -i ... -b ... -o ... — invoked only when --docx is omitted
check_xref.py --md ... --docx ... --strict [--allow-separate-attachments]
On success the chain writes qc/pre_submission_gate.json (plus the
per-stage artifacts qc/reference_audit.json and qc/xref_audit.json)
with submission_safe: true. On any failure the JSON records the failing
stage and exit code, and the script exits non-zero — do not submit until
the failing stage passes.
Critical: the gate does not reimplement any check. It calls the existing
scripts as subprocesses. If you find yourself wanting to add a check, add it
to the underlying script (the gate then picks it up automatically).
F. BibTeX author-format corruption (rendered-name check)
Entries written as author = {Surname AB and Surname2 CD} (family + initials, no comma) make BibTeX treat the last token as the family name, rendering "AB S, CD S2". Always store author = {Family, Full Given}. Concatenated initials even with a comma (Family, AB) still collapse to a single initial under CSL initialize-with, so use the full forename from PubMed efetch.
/verify-refs compares bib content against PubMed but does not see the rendered output; grep the rendered docx and the bib separately:
unzip -p out.docx word/document.xml | sed 's/<[^>]*>//g' | grep -oE "[A-Z]{2} [A-Z], [A-Z]{2} [A-Z]" # corruption signature in output
grep -nE 'author\s*=\s*\{[A-Z][a-z]+ [A-Z]{1,3}( |\})' refs.bib # no-comma source entries
Quality Gates
This skill defines three submission gates and one user approval gate:
- Gate 1 (citekey integrity):
check_citation_keys.py exits non-zero on
UNDEFINED keys. The pipeline halts; the user reviews and fixes.
- Gate 2 (cross-reference integrity):
check_xref.py --strict exits 1 on
any MISSING_DOCX / MISSING_BODY / MISMATCH row. The user reviews
qc/xref_audit.json and resolves before proceeding. Under
--allow-separate-attachments, check summary.downgraded_unchecked as well as
submission_safe: a non-zero count means rows passed without being checked.
- Gate 3 (audit hand-off): before sign-off, the user must run
/verify-refs and confirm submission_safe: true in
qc/reference_audit.json. This skill never marks the bibliography
audited on its own.
- User approval gate (CWYW first build): the user must perform Word →
Zotero → Add/Edit Bibliography manually after the first
inject_zotero_cwyw.py build. The skill cannot automate this and warns
on stderr that it is required.
Provenance
scripts/_vendor_citation_writer.py is vendored from
alisoroushmd/zotero-mcp @ ed5dfb71, MIT licensed. See
NOTICE.md and LICENSE.zotero-mcp.
Related
~/.claude/rules/manuscript-references.md — global rule (decision tree
this skill implements)
~/.claude/rules/agent-skill-routing.md — skill router (this skill is the
reference-handling row)
~/.claude/rules/zotero-workflow.md — BBT auto-export, MCP setup
/verify-refs — read-only audit (PubMed / CrossRef + first-author
cross-check)
/lit-sync — Zotero ↔ Obsidian sync, refs.bib provider
/write-paper Phase 7.6 — calls this skill (one-line delegation)
/revise, /sync-submission, /find-journal — call this skill on
rebuild / re-render / cascade
Known Limitations
- First-build empty BIBL field (CWYW):
inject_zotero_cwyw.py writes a
stub ADDIN ZOTERO_BIBL field; Word's Zotero Refresh treats an empty
stub as user-customized and refuses to populate it. User must run
Add/Edit Bibliography once. Subsequent Refresh works as expected.
Validated on Word for Mac, an active meta-analysis project.
- Webpage / non-journal item types: handled by the patched
zotero_to_csl_json that fetches Zotero's native CSL-JSON; do not bypass
this patch.
- Surgical post-build regex patches are unsafe — see Workflow B step 5.
- Local Zotero required for CWYW — port 23119 must be reachable; no
web-API fallback yet (would need
ZOTERO_API_KEY). On failure the script
aborts with non-zero exit so partial builds never ship.
Global-rule references
Some passages in this skill cite a path of the form ~/.claude/rules/<name>.md. Those are the
maintainer's personal global rules, kept outside this repository. They are not shipped with
this skill and will not exist on your machine; they appear only as provenance for where a
convention came from. If one of them looks like it is standing in for an instruction you actually
need, that is a bug — please open an issue, because the instruction belongs here.
1---2name: manage-refs3description: >4 Cross-cutting reference manager for medical manuscripts. Single entry point5 for citation-key validation, journal-CSL pandoc rendering, manuscript ↔ DOCX6 cross-reference QC, marker conversion (``[N]`` ↔ ``[@key]``), and native7 Zotero CWYW field-code injection. Replaces the inline reference-handling8 that previously lived in ``/write-paper`` Phase 7.6 and is reused by9 ``/revise``, ``/peer-review``, ``/sync-submission``, and any skill that10 produces a journal submission. Audit-only verification stays in11 ``/verify-refs`` — this skill writes (renders, injects, converts); that12 skill only reads.13triggers: manage-refs, references, citation, citation keys, pandoc citeproc, journal CSL, CSL swap, cascade rejection re-render, cross-reference QC, [@bibkey], Zotero CWYW, ADDIN ZOTERO_ITEM, marker conversion, [N] to [@key], reference manager, render manuscript, check_citation_keys, check_xref14tools: Read, Write, Edit, Bash, Grep, Glob15model: inherit16metadata:17 source: https://skillmd.com/skills/aperivue/manage-refs18---1920# Manage-Refs Skill2122> **Canonical source (issue #16).** This SKILL.md is the single canonical23> reference for the reference-*workflow* (validate keys → render CSL → convert24> markers → QC cross-references → inject Zotero CWYW). Audit-only bib25> verification is owned by `skills/verify-refs/SKILL.md`. Any user-scope rule or26> external note about reference handling should point here (workflow) or to27> verify-refs (audit) rather than restating the "how", to prevent drift.2829You are routing reference-handling work for a medical manuscript. The user is30somewhere in the lifecycle — drafting, building a circulation DOCX, swapping31CSL after a journal rejection, fixing a cross-reference defect surfaced by32QC, or wiring up live Zotero field codes for a co-author Word workflow. Pick33the right tool from the decision table; do not invent a parallel pipeline.3435## Why This Skill Exists3637Reference handling spans every late-stage skill: `/write-paper` builds the38first DOCX, `/revise` rebuilds it after each reviewer round, `/peer-review`39emits a critique that quotes references back, `/sync-submission` packages the40final tarball, `/find-journal` informs CSL swaps on rejection cascade, and41`/verify-refs` audits the bibliography. Until 2026-05-01 these scripts lived42under `skills/write-paper/scripts/`, which made `/revise` and `/sync-submission`43silently depend on a sibling skill — a layering inversion that broke when44`/write-paper` was loaded into a non-research project. Moving the45lifecycle tools here turns reference handling into a first-class concern46with one decision tree, one set of CSL files, and one provenance file47(`NOTICE.md`) for the vendored Zotero CWYW writer.4849Validated 2026-05-01 against a 21-reference meta-analysis manuscript50(a meta-analysis project's submission) for both pandoc-citeproc and Zotero-CWYW paths.5152## Anti-Hallucination Guarantees53541. **Citekey discipline (Phase 0)**: every in-text citation must be55 `[@bibkey]` resolvable in `refs.bib`. `scripts/check_citation_keys.py` is56 a hard gate — UNDEFINED keys exit non-zero and block the build.5758 **`[@NEW:topic]` placeholder convention**: while drafting, `/write-paper`59 may emit `[@NEW:topic_slug]` markers for citations the author still needs60 to source. `check_citation_keys.py` classifies these as `NEW_PLACEHOLDER`61 (not UNDEFINED) and exits 0 — the build is allowed to proceed during62 drafting. Phase 7.6 (DOCX render) is a hard gate: zero NEW_PLACEHOLDER63 entries must remain. Resolve each by adding the citation to Zotero (then64 `/lit-sync` refreshes refs.bib) and replacing the placeholder with the65 real `[@bibkey]`. Never let a `[@NEW:...]` reach a rendered DOCX.662. **No hand-typed References list** — references are always rendered by67 pandoc citeproc + journal CSL or by the Zotero Word plugin (CWYW). See68 `~/.claude/rules/manuscript-references.md`.693. **Zotero metadata is never invented** — `inject_zotero_cwyw.py` fetches70 item data live from `http://localhost:23119`. Any HTTP failure aborts71 with a non-zero exit so partial bibliographies never reach the user.724. **Marker conversion is mapping-driven** — `md_marker_convert.py` will73 never guess a Zotero key for a number; unmapped markers stay as `[N]`74 and are reported on stderr.755. **Cross-reference QC is a submission gate** — `scripts/check_xref.py`76 `--strict` exits 1 on any `MISSING_DOCX` / `MISSING_BODY` / `MISMATCH`,77 blocking pipelines that try to ship a DOCX whose Table/Figure citations78 don't match captions. `--allow-separate-attachments` downgrades the two79 rows a separate-attachment submission legitimately produces; it never80 downgrades a `MISSING_BODY` whose float IS in the rendered DOCX.816. **Audit boundary**: this skill writes; bibliographic correctness against82 PubMed/CrossRef stays in `/verify-refs`. Always invoke `/verify-refs`83 after a render before signing off — one read-only audit, one writer.8485## Decision Tree8687| Situation | Tool | Why |88|---|---|---|89| Validate `[@bibkey]` ↔ `refs.bib` (UNDEFINED / UNUSED keys) | `scripts/check_citation_keys.py` | Hard build gate, runs in seconds |90| Single-author submission lockdown, frozen output | `scripts/render_pandoc.sh -j <journal>` | Reproducible, CI-friendly |91| Cascade rejection (e.g., ER → JVIR → CVIR) | `render_pandoc.sh` with new `-j` | CSL swap reformats references in seconds |92| 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 |93| 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 |94| 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 |95| Reviewer revision: bulk reference change | Edit markdown SSOT, re-run `render_pandoc.sh` | Consistency, no cherry-pick risk |96| Migrate `[N]` numeric markers → `[@key]` for pandoc | `scripts/md_marker_convert.py --to-keys` | Mapping-driven, partial conversion safe |97| Convert `[@key]` → `[N]` for round-trip / debug | `scripts/md_marker_convert.py --to-numbers` | Same map, opposite direction |98| 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 |99| Manuscript ↔ rendered DOCX cross-reference QC | `scripts/check_xref.py --strict` | Submission gate (P0 blocker on mismatch) |100| 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 |101| **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 |102| **Duplicate bibliography in the built artifact** | `scripts/check_reference_duplication.py --docx <built>.docx` (or `--text <rendered>.md`) | Fires when the reference list is duplicated — `DUP_REF_HEADING` / `REF_NUMBER_RESTART` / `REF_SIGNATURE_DUP` (Major). Catches the hybrid hand-typed `## References` list + pandoc `--citeproc` auto-bibliography, which renders **two** lists (the second often after the legends). Run after any citeproc build |103| **Publisher markup in a `.bib` title** (renders as garbage) | `scripts/check_bib_title_markup.py --bib refs.bib --strict` | CrossRef ships `<scp>WHO</scp>` / `<i>IDH</i>` in titles and a DOI-add stores them verbatim; BBT then escapes them (`{$<$}scp{$>$}`) or strips them without restoring the space (`andTERTPromoter`, `1p/19q,IDH`). `verify_refs` proves the reference is *true*; this proves it will *print*. `TITLE_MARKUP` / `TITLE_FUSION` (Major) |104| **Master pre-submission gate** (recommended before any submission) | `scripts/pre_submission_gate.sh` | Chains `check_citation_keys` → `check_bib_title_markup` → `verify_refs --strict` → `render_pandoc` (optional) → `check_xref --strict`; single artifact `qc/pre_submission_gate.json` |105| Direct render with a built-in reference audit | `scripts/render_pandoc.sh` (audits the `.bib` via `/verify-refs` first; blocks on FABRICATED/MISMATCH/duplicates) | Defense-in-depth so even a direct render call cannot ship hallucinated citations; best-effort (skips with a warning if `/verify-refs` is not alongside), opt out with `-S`. The master gate passes `-S` since it audits in stage 2 |106| Bibliographic audit against PubMed / CrossRef | **delegate** to `/verify-refs` | Audit-only — keep writer/auditor separation |107108## Workflows109110### A. Pandoc citeproc (default for solo authors and final submissions)111112User provides `manuscript.md` with `[@bibkey]` citations + `refs.bib`.1131. **Gate**: `python "${CLAUDE_SKILL_DIR}/scripts/check_citation_keys.py" manuscript.md refs.bib`114 — exits non-zero on UNDEFINED keys. Fix and re-run.1152. **Render**:116 ```bash117 "${CLAUDE_SKILL_DIR}/scripts/render_pandoc.sh" \118 -j european-radiology \119 -i manuscript.md \120 -b refs.bib \121 -o manuscript_final.docx122 ```123 For the current inventory and what each style renders, read124 `citation_styles/README.md` — that table is the registry. `render_pandoc.sh` also lists125 what is on disk when `-j` names a style it cannot find, so ask the script rather than126 trusting a list written here. Two standing fallbacks: use `radiology` for RYAI and127 `vancouver` for JVIR (neither has a dedicated CSL).1283. **QC**:129 ```bash130 python3 "${CLAUDE_SKILL_DIR}/scripts/check_xref.py" \131 --md manuscript.md --docx manuscript_final.docx \132 --out qc/xref_audit.json --strict133 ```134 Treat `submission_safe: false` as a halt. Route fixes by symptom — see135 the table in `references/check_xref_symptoms.md`.1364. **Audit hand-off**: invoke `/verify-refs` for the PubMed/CrossRef audit137 before sign-off.138139### B. Zotero CWYW (co-author Word workflow)140141User has a markdown SSOT and wants reviewers to edit citations directly in142Word. Each reference must already exist as a Zotero item; the user supplies143a `[N] → ZoteroKey` mapping.1441. **Convert markers**:145 ```bash146 python3 "${CLAUDE_SKILL_DIR}/scripts/md_marker_convert.py" \147 --input manuscript.md --output manuscript_keys.md \148 --map ref_map.json --to-keys149 ```150 Optionally stage with `--active-ns 1,2,3,4,19` for a sample build first151 (validated on an active meta-analysis project: 5-ref sample reduces Word Refresh blast radius152 when debugging).1532. **Render to .docx** with pandoc (workflow A) so the body has plain text154 `[@key]` markers, OR pre-build a .docx some other way that still contains155 plain `[@key]` text.1563. **Inject CWYW**:157 ```bash158 python3 "${CLAUDE_SKILL_DIR}/scripts/inject_zotero_cwyw.py" \159 --input manuscript_keys.docx --output manuscript_cwyw.docx \160 --user-id 16613550 --keys-from keys.txt161 ```162 The script fetches Zotero metadata via the local connector (port 23119);163 any HTTP failure aborts with non-zero exit.1644. **First-build instruction** (REQUIRED — see Known Limitation #1): open165 the output in Word → Zotero tab → **Add/Edit Bibliography** once. After166 that, **Refresh** keeps citations and bibliography in sync as authors167 edit.1685. **Surgical patches are unsafe**: for ref additions in later rounds, edit169 the markdown SSOT and rebuild the whole .docx instead of regex-patching170 the post-CWYW file. Zotero's rendered `[N]` superscripts can collide171 with plain `[N]` markers and corrupt the field codes.172173### C. Cascade rejection re-render (find-journal hand-off)174175User got rejected from journal A and `/find-journal` recommended journal B.1761. Confirm the new CSL exists in `citation_styles/` (or fetch from177 https://citationstyles.org/styles and drop in).1782. Re-run `render_pandoc.sh -j <new-csl>` against the same `manuscript.md` +179 `refs.bib`.1803. Re-run `check_xref.py --strict`.1814. Re-run `/verify-refs` if any new references were added during the182 inter-journal revision.183184### D. Cross-reference QC only185186User shipped a manuscript and a reviewer flagged a Table/Figure mismatch.1871. Run `check_xref.py --strict` on the current `manuscript.md` + `.docx`.1882. Inspect `qc/xref_audit.json`. Body caption is the SSOT — fix `manuscript.md`189 and rebuild, never patch the .docx by hand.1903. See `references/check_xref_symptoms.md` for the191 `MISSING_BODY` / `MISSING_DOCX` / `MISMATCH` triage table.1924. For journals that accept figures and tables as **separate attachment files**193 (the default in European Radiology, Radiology, AJR, JVIR, KJR, and most194 medical journals), pass `--allow-separate-attachments`. It downgrades two195 rows, and the run reports them apart because their evidence differs:196197 - `MISSING_DOCX` — a `--docx` was supplied and **proved** the float is not in198 the rendered main document. That is what a separate attachment looks like.199 - `MISSING_BODY` with **no `--docx` supplied** — nothing was checked. The float200 is either separately attached, as you declared, or a caption nobody wrote.201 Excused on your word, printed as `EXCUSED WITHOUT EVIDENCE`, and counted in202 `summary.downgraded_unchecked`.203204 `MISMATCH` stays P0. So does `MISSING_BODY` when the float **is** in the205 rendered DOCX — that is SSOT drift, and no attachment policy makes the build206 pipeline an acceptable single source of truth for a caption.207208 **Run once with `--docx` before submitting.** The flag is a declaration, not a209 verification; supplying the DOCX is what converts an excuse into evidence.210211### D'. v_(N+1) docx regeneration check (build-time companion)212213When building v_(N+1) from a frozen v_N, the v_(N+1) docx MUST differ214from v_N docx by content — a byte-identical copy is a silent seed-copy215that will revert markdown edits at peer review. `check_xref.py` carries216two flags for the build-time companion to the submission-time gate217in `scripts/verify_package_integrity.py --assert-vN-docx-changed`:218219```bash220python3 "${CLAUDE_SKILL_DIR}/scripts/check_xref.py" \221 --md manuscript_v2.md \222 --docx manuscript_v2.docx \223 --vN-docx-md5 manuscript_v1.docx \224 --vN-md manuscript_v1.md \225 --strict226```227228- `--vN-docx-md5` alone: MD5 identity check. Identical bytes = FAIL.229- `--vN-docx-md5 + --vN-md`: additionally extracts the markdown-only diff230 between v_N and v_(N+1) and verifies each ≥40-char diff line appears231 verbatim (whitespace-normalized, case-insensitive) in the new docx232 body XML. Missing diff lines = body did not pick up the markdown edits.233234Output records the result under `vN_docx_check` in `qc/xref_audit.json`.235Either failure mode causes a non-zero exit even without `--strict`.236237### E. Master pre-submission gate (recommended end-to-end chain)238239The single entry point that combines workflows A and D plus `/verify-refs`240into one aborting chain. Use this immediately before submission or before241circulating a v_N package to senior co-authors.242243```bash244bash "${CLAUDE_SKILL_DIR}/scripts/pre_submission_gate.sh" \245 --md manuscript/manuscript.md \246 --bib manuscript/_src/refs.bib \247 --docx submission/<journal>/manuscript.docx \248 --allow-separate-attachments # omit if the journal accepts inline figures/tables249```250251Stage order (first failure aborts):2521. `check_citation_keys.py manuscript.md refs.bib` — UNDEFINED / UNUSED keys2532. `verify_refs.py refs.bib --strict` — PubMed / CrossRef per-entry verification2543. `render_pandoc.sh -j <csl> -i ... -b ... -o ...` — invoked only when `--docx` is omitted2554. `check_xref.py --md ... --docx ... --strict [--allow-separate-attachments]`256257On success the chain writes `qc/pre_submission_gate.json` (plus the258per-stage artifacts `qc/reference_audit.json` and `qc/xref_audit.json`)259with `submission_safe: true`. On any failure the JSON records the failing260stage and exit code, and the script exits non-zero — do not submit until261the failing stage passes.262263Critical: the gate does **not** reimplement any check. It calls the existing264scripts as subprocesses. If you find yourself wanting to add a check, add it265to the underlying script (the gate then picks it up automatically).266267### F. BibTeX author-format corruption (rendered-name check)268269Entries written as `author = {Surname AB and Surname2 CD}` (family + initials, **no comma**) make BibTeX treat the last token as the family name, rendering "AB S, CD S2". Always store `author = {Family, Full Given}`. Concatenated initials even with a comma (`Family, AB`) still collapse to a single initial under CSL `initialize-with`, so use the full forename from PubMed `efetch`.270271`/verify-refs` compares bib content against PubMed but does not see the rendered output; grep the rendered docx and the bib separately:272273```bash274unzip -p out.docx word/document.xml | sed 's/<[^>]*>//g' | grep -oE "[A-Z]{2} [A-Z], [A-Z]{2} [A-Z]" # corruption signature in output275grep -nE 'author\s*=\s*\{[A-Z][a-z]+ [A-Z]{1,3}( |\})' refs.bib # no-comma source entries276```277278## Quality Gates279280This skill defines **three submission gates** and **one user approval gate**:281282- **Gate 1 (citekey integrity)**: `check_citation_keys.py` exits non-zero on283 UNDEFINED keys. The pipeline halts; the user reviews and fixes.284- **Gate 2 (cross-reference integrity)**: `check_xref.py --strict` exits 1 on285 any `MISSING_DOCX` / `MISSING_BODY` / `MISMATCH` row. The user reviews286 `qc/xref_audit.json` and resolves before proceeding. Under287 `--allow-separate-attachments`, check `summary.downgraded_unchecked` as well as288 `submission_safe`: a non-zero count means rows passed without being checked.289- **Gate 3 (audit hand-off)**: before sign-off, the user must run290 `/verify-refs` and confirm `submission_safe: true` in291 `qc/reference_audit.json`. This skill never marks the bibliography292 audited on its own.293- **User approval gate (CWYW first build)**: the user must perform Word →294 Zotero → Add/Edit Bibliography manually after the first295 `inject_zotero_cwyw.py` build. The skill cannot automate this and warns296 on stderr that it is required.297298## Provenance299300`scripts/_vendor_citation_writer.py` is vendored from301`alisoroushmd/zotero-mcp` @ `ed5dfb71`, MIT licensed. See302[`NOTICE.md`](./NOTICE.md) and [`LICENSE.zotero-mcp`](./LICENSE.zotero-mcp).303304## Related305306- `~/.claude/rules/manuscript-references.md` — global rule (decision tree307 this skill implements)308- `~/.claude/rules/agent-skill-routing.md` — skill router (this skill is the309 reference-handling row)310- `~/.claude/rules/zotero-workflow.md` — BBT auto-export, MCP setup311- `/verify-refs` — read-only audit (PubMed / CrossRef + first-author312 cross-check)313- `/lit-sync` — Zotero ↔ Obsidian sync, `refs.bib` provider314- `/write-paper` Phase 7.6 — calls this skill (one-line delegation)315- `/revise`, `/sync-submission`, `/find-journal` — call this skill on316 rebuild / re-render / cascade317318## Known Limitations3193201. **First-build empty BIBL field (CWYW)**: `inject_zotero_cwyw.py` writes a321 stub `ADDIN ZOTERO_BIBL` field; Word's Zotero Refresh treats an empty322 stub as user-customized and refuses to populate it. User must run323 Add/Edit Bibliography once. Subsequent Refresh works as expected.324 Validated on Word for Mac, an active meta-analysis project.3252. **Webpage / non-journal item types**: handled by the patched326 `zotero_to_csl_json` that fetches Zotero's native CSL-JSON; do not bypass327 this patch.3283. **Surgical post-build regex patches are unsafe** — see Workflow B step 5.3294. **Local Zotero required for CWYW** — port 23119 must be reachable; no330 web-API fallback yet (would need `ZOTERO_API_KEY`). On failure the script331 aborts with non-zero exit so partial builds never ship.332333## Global-rule references334335Some passages in this skill cite a path of the form `~/.claude/rules/<name>.md`. Those are the336maintainer's personal global rules, kept outside this repository. They are **not shipped with337this skill** and will not exist on your machine; they appear only as provenance for where a338convention came from. If one of them looks like it is standing in for an instruction you actually339need, that is a bug — please open an issue, because the instruction belongs here.