manage-refs

Files (72)

• LICENSE.zotero-mcp
• NOTICE.md
• SKILL.md
• README.md · citation_styles/
• american-association-for-cancer-research.csl · citation_styles/
• american-journal-of-roentgenology.csl · citation_styles/
• american-medical-association.csl · citation_styles/
• annals-of-oncology.csl · citation_styles/
• breast-cancer-research-and-treatment.csl · citation_styles/
• cardiovascular-and-interventional-radiology.csl · citation_styles/
• clinical-breast-cancer.csl · citation_styles/
• clinical-cancer-research.csl · citation_styles/
• elsevier-vancouver.csl · citation_styles/
• european-radiology.csl · citation_styles/
• journal-of-breast-cancer.csl · citation_styles/
• journal-of-cachexia-sarcopenia-and-muscle.csl · citation_styles/
• journal-of-clinical-oncology.csl · citation_styles/
• journal-of-korean-medical-science-strict.csl · citation_styles/
• journal-of-korean-medical-science.csl · citation_styles/
• korean-journal-of-radiology.csl · citation_styles/
• liver-international.csl · citation_styles/
• methods-of-information-in-medicine.csl · citation_styles/
• nature.csl · citation_styles/
• nlm-citation-sequence.csl · citation_styles/
• radiology.csl · citation_styles/
• springer-basic-brackets.csl · citation_styles/
• springer-vancouver-brackets.csl · citation_styles/
• the-breast.csl · citation_styles/
• the-lancet-oncology.csl · citation_styles/
• the-lancet.csl · citation_styles/
• vancouver-superscript.csl · citation_styles/
• vancouver.csl · citation_styles/
• REFERENCE_STYLE_SPECS.md · references/
• check_xref_symptoms.md · references/
• _vendor_citation_writer.py · scripts/
• check_bib_title_markup.py · scripts/
• check_citation_keys.py · scripts/
• manuscript.md · scripts/check_citation_keys_challenge/fixture/
• refs_clean.bib · scripts/check_citation_keys_challenge/fixture/
• refs_undefined.bib · scripts/check_citation_keys_challenge/fixture/
• verify.sh · scripts/check_citation_keys_challenge/
• check_csl_render.py · scripts/
• check_reference_duplication.py · scripts/
• check_xref.py · scripts/
• fill_journal_abbrev.py · scripts/
• inject_zotero_cwyw.py · scripts/
• md_marker_convert.py · scripts/
• pre_submission_gate.sh · scripts/
• render_pandoc.sh · scripts/
• strip_source_metadata.lua · scripts/
• skill.yml
• csl_render_sample.bib · tests/fixtures/
• README.md · tests/fixtures/pre_submission_gate/
• manuscript.md · tests/fixtures/pre_submission_gate/
• refs.bib · tests/fixtures/pre_submission_gate/
• run.sh · tests/fixtures/pre_submission_gate/
• refclean_text.md · tests/fixtures/
• refcount_particles.md · tests/fixtures/
• refdup_particles.md · tests/fixtures/
• refdup_text.md · tests/fixtures/
• …and 12 more

SKILL.md (first lines)

# Manage-Refs Skill

Pick the tool from the Decision Tree; do not invent a parallel pipeline. References are never
hand-typed: the list is always rendered by pandoc citeproc + journal CSL or by the Zotero Word
plugin (CWYW). This skill writes (renders, injects, converts); bibliographic correctness against
PubMed/CrossRef stays in `/verify-refs` — 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> --md manuscript.md` | A stub/"dependent" CSL inherits its parent's format, which may differ from the guide (parenthetical vs superscript, DOI kept, full journal names). `--md` judges only the keys pandoc reads as cited (`nocite: '@*'` = whole bib); a preprint server named as the journal (`journal = {arXiv}`) is exempt from the abbreviation check; with no `--journal`/`--expect-*` the run is NOT_ASSESSED (exit 2), never PASS. Spec keys and what is not checked: `references/REFERENCE_STYLE_SPECS.md`. 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 --bib refs.bib --out refs_abbrev.bib` | Writes `shortjournal` from PubMed (PMID, else DOI → PMID), then CrossRef `short-container-title`, named per entry (often ISO 4 with periods, not NLM: check those). Inserts after the journal field in the entry's own indentation, never overwrites, re-parses before writing; exit 1 = some lookups failed. In a Better BibTeX-managed bib, fill Zotero's "Journal Abbr" instead |
| 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]` | 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`) | `DUP_REF_HEADING` / `REF_NUMBER_RESTART` / `REF_SIGNATURE_DUP` (Major). Catches a hand-typed `## References` list plus the 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 titles carry `<scp>WHO</scp>` / `<i>IDH</i>`; BBT escapes them (`{$<$}scp{$>$}`) or strips them without restoring the space (`andTERTPromoter`). `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; reports UNVERIFIED rows as not clean, without blocking; after the render, warns about cited journal entries without `shortjournal`, which the style prints in full) | Best-effort (skips with a warning if `/verify-refs` is not alongside); opt out with `-S`. The master gate passes `-S` because it runs `verify_refs` in its stage 3 |
| 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**: `python3 "${CLAUDE_SKILL_DIR}/scripts/check_citation_keys.py" manuscript.md refs.bib`
   — exits non-zero on UNDEFINED keys. Fix and re-run. A `[@NEW:topic_slug]` drafting
   placeholder from `/write-paper` is reported as UNDEFINED too: resolve each by adding the
   citation to Zotero (`/lit-sync` then refreshes `refs.bib`) and replacing the placeholder with
   the real `[@bibkey]`. Never let a `[@NEW:...]` reach a rendered DOCX.
2. **Render**:
   ```bash
   "${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).
   A cited key that is not in the `.bib` makes the render exit 5 and name the key: pandoc
   prints it as `(key?)` in the output and does not fail on its own.
3. **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`.
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**:
   ```bash
   python3 "${CLAUDE_SKILL_DIR}/scripts/md_marker_convert.py" \
     --input manuscript.md --output manuscript_keys.md \
     --map ref_map.json --to-keys
   ```
   The conversion never guesses a Zotero key for a number: unmapped markers stay as `[N]`, are
   reported on stderr, and make the script exit 1 (the partial output is still written; pass
   `--allow-partial` to accept it). Ranges such as `[1-3]` are expanded. Any bracketed
   number counts as a marker, so a year in brackets (`[2019-2021]`) is reported UNMAPPED too. Optionally stage with `--active-ns 1,2,3,4,19` for a sample build
   first (a 5-reference sample limits the Word Refresh blast radius while 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**:
   ```bash
   python3 "${CLAUDE_SKILL_DIR}/scripts/inject_zotero_cwyw.py" \
     --input manuscript_keys.docx --output manuscript_cwyw.docx \
     --user-id <zotero-user-id> --keys-from keys.txt
   ```
   The script fetches item metadata live from the local Zotero connector (port 23119), so
   Zotero must be running locally; there is no web-API fallback. Any HTTP failure aborts with a
   non-zero exit, so a partial bibliography never reaches the user. Never invent Zotero metadata.
4. **First-build instruction** (REQUIRED): the script writes an empty `ADDIN ZOTERO_BIBL`
   stub, which Word's Zotero Refresh treats as user-customized and refuses to populate. Open
   the output in Word → Zotero tab → **Add/Edit Bibliography** once. After that, **Refresh**
   keeps citations and bibliography in sync as authors edit.
5. **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.
1. Confirm the new CSL exists in `citation_styles/` (or fetch from
   https://citationstyles.org/styles and drop in).
2. Re-run `render_pandoc.sh -j <new-csl>` against the same `manuscript.md` +
   `refs.bib`.
3. Re-run `check_xref.py --strict`.
4. 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.
1. Run `check_xref.py --strict` on the current `manuscript.md` + `.docx`.
2. Inspect `qc/xref_audit.json`. Body caption is the SSOT — fix `manuscript.md`

From Aperivue/medsci-skills, MIT.

More from Aperivue/medsci-skills