git:20260929.2b7013d to git:20260930.c83ad00

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

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

- | **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) |

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

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

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

- --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 authors

- edit.

- (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_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`.

- rendered DOCX — that is SSOT drift, and no attachment policy makes the build

- pipeline an acceptable single source of truth for a caption.

- 2. `verify_refs.py refs.bib --strict` — PubMed / CrossRef per-entry verification

- 3. `render_pandoc.sh -j <csl> -i ... -b ... -o ...` — invoked only when `--docx` is omitted

- 4. `check_xref.py --md ... --docx ... --strict [--allow-separate-attachments]`

- per-stage artifacts `qc/reference_audit.json` and `qc/xref_audit.json`)

- with `submission_safe: true`. On any failure the JSON records the failing

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

- ## 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

-

- 1. **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.

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

- 3. **Surgical post-build regex patches are unsafe** — see Workflow B step 5.

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