medsci-skills 4.1.0

package/skills/manage-refs/citation_styles/vancouver.csl

@@ -0,0 +1,535 @@
+<?xml version="1.0" encoding="utf-8"?>
+<style xmlns="http://purl.org/net/xbiblio/csl" class="in-text" delimiter-precedes-last="always" demote-non-dropping-particle="sort-only" initialize-with="" initialize-with-hyphen="false" name-as-sort-order="all" name-delimiter=", " names-delimiter=", " page-range-format="minimal" sort-separator=" " version="1.0">
+  <!-- This file was generated by the Style Variant Builder <https://github.com/citation-style-language/style-variant-builder>. To contribute changes, modify the template and regenerate variants. -->
+  <info>
+    <title>NLM/Vancouver: Citing Medicine 2nd edition (citation-sequence)</title>
+    <title-short>National Library of Medicine, ANSI/NISO Z39.29-2005 (R2010), ICMJE Recommendations/URMs (C-S)</title-short>
+    <id>http://www.zotero.org/styles/nlm-citation-sequence</id>
+    <link href="http://www.zotero.org/styles/nlm-citation-sequence" rel="self"/>
+    <link href="https://www.nlm.nih.gov/citingmedicine" rel="documentation"/>
+    <link href="https://www.nlm.nih.gov/bsd/uniform_requirements.html" rel="documentation"/>
+    <link href="https://www.icmje.org/recommendations/" rel="documentation"/>
+    <author>
+      <name>Michael Berkowitz</name>
+      <email>mberkowi@gmu.edu</email>
+    </author>
+    <author>
+      <name>Andrew Dunning</name>
+      <uri>https://orcid.org/0000-0003-0464-5036</uri>
+    </author>
+    <contributor>
+      <name>Petr Hlustik</name>
+      <uri>https://orcid.org/0000-0002-1951-0671</uri>
+    </contributor>
+    <contributor>
+      <name>Sebastian Karcher</name>
+      <uri>https://orcid.org/0000-0001-8249-7388</uri>
+    </contributor>
+    <contributor>
+      <name>Charles Parnot</name>
+      <uri>https://orcid.org/0000-0002-7346-5883</uri>
+    </contributor>
+    <contributor>
+      <name>Sean Takats</name>
+      <uri>https://orcid.org/0000-0002-7851-5069</uri>
+    </contributor>
+    <category citation-format="numeric"/>
+    <category field="generic-base"/>
+    <category field="medicine"/>
+    <category field="science"/>
+    <summary>Citing Medicine: The NLM Style Guide for Authors, Editors, and Publishers, 2nd edition (2015), based on ANSI/NISO Z39.29-2005 (R2010); citation-sequence system.</summary>
+    <updated>2026-03-29T15:20:09+00:00</updated>
+    <rights license="http://creativecommons.org/licenses/by-sa/3.0/">This work is licensed under a Creative Commons Attribution-ShareAlike 3.0 License</rights>
+  </info>
+  <locale xml:lang="en">
+    <date delimiter=" " form="text">
+      <date-part name="year"/>
+      <date-part form="short" name="month" strip-periods="true"/>
+      <date-part name="day"/>
+    </date>
+    <terms>
+      <term name="available at">available from</term>
+      <term name="collection-editor">
+        <single>editor</single>
+        <multiple>editors</multiple>
+      </term>
+      <term form="short" name="month-06">Jun.</term>
+      <term form="short" name="month-07">Jul.</term>
+      <term form="short" name="month-09">Sep.</term>
+      <term name="presented at">presented at</term>
+      <term form="short" name="section">
+        <single>sect.</single>
+        <multiple>sects.</multiple>
+      </term>
+      <term form="short" name="supplement">
+        <single>suppl.</single>
+        <multiple>suppls.</multiple>
+      </term>
+    </terms>
+  </locale>
+  <locale xml:lang="fr">
+    <date delimiter=" " form="text">
+      <date-part name="day"/>
+      <date-part form="short" name="month" strip-periods="true"/>
+      <date-part name="year"/>
+    </date>
+  </locale>
+  <!-- Variable labels -->
+  <macro name="label-collection-number">
+    <group delimiter=" ">
+      <choose>
+        <if is-numeric="collection-number">
+          <label form="short" variable="collection-number"/>
+        </if>
+      </choose>
+      <text variable="collection-number"/>
+    </group>
+  </macro>
+  <macro name="label-edition">
+    <group delimiter=" ">
+      <choose>
+        <if is-numeric="edition">
+          <number form="ordinal" variable="edition"/>
+          <label form="short" variable="edition"/>
+        </if>
+        <else>
+          <text variable="edition"/>
+        </else>
+      </choose>
+    </group>
+  </macro>
+  <macro name="label-number">
+    <group delimiter=": ">
+      <choose>
+        <if type="standard"/>
+        <else-if is-numeric="number" match="any" type="legislation patent regulation">
+          <label form="short" variable="number"/>
+        </else-if>
+      </choose>
+      <text variable="number"/>
+    </group>
+  </macro>
+  <macro name="label-number-of-pages">
+    <group delimiter=" ">
+      <text variable="number-of-pages"/>
+      <choose>
+        <if is-numeric="number-of-pages">
+          <label form="short" plural="never" variable="number-of-pages"/>
+        </if>
+      </choose>
+    </group>
+  </macro>
+  <macro name="label-page">
+    <group delimiter=" ">
+      <label form="short" plural="never" variable="page"/>
+      <text variable="page"/>
+    </group>
+  </macro>
+  <macro name="label-part-number-capitalized">
+    <group delimiter=" ">
+      <choose>
+        <if is-numeric="part-number">
+          <!-- TODO: Replace with `part-number` label when CSL provides one -->
+          <text form="short" term="part" text-case="capitalize-first"/>
+        </if>
+      </choose>
+      <text variable="part-number"/>
+    </group>
+  </macro>
+  <macro name="label-supplement-number">
+    <group delimiter=" ">
+      <choose>
+        <if is-numeric="supplement-number">
+          <!-- TODO: Replace with `supplement-number` label when CSL provides one -->
+          <text form="short" strip-periods="true" term="supplement" text-case="capitalize-first"/>
+        </if>
+      </choose>
+      <text text-case="capitalize-first" variable="supplement-number"/>
+    </group>
+  </macro>
+  <macro name="label-volume-capitalized">
+    <group delimiter=" ">
+      <choose>
+        <if is-numeric="volume">
+          <label form="short" text-case="capitalize-first" variable="volume"/>
+        </if>
+      </choose>
+      <text variable="volume"/>
+    </group>
+  </macro>
+  <macro name="author">
+    <names variable="author">
+      <label prefix=", "/>
+      <substitute>
+        <names variable="editor-translator"/>
+        <names variable="editor translator"/>
+        <names variable="editor"/>
+        <names variable="collection-editor"/>
+      </substitute>
+    </names>
+  </macro>
+  <macro name="title">
+    <choose>
+      <if type="webpage" variable="container-title">
+        <!-- `webpage` listed under `container-title` (Citing Medicine, ch. 25) -->
+        <text variable="container-title"/>
+      </if>
+      <else>
+        <text variable="title"/>
+      </else>
+    </choose>
+  </macro>
+  <macro name="content-type">
+    <text variable="genre"/>
+  </macro>
+  <macro name="type-of-medium">
+    <choose>
+      <if variable="medium">
+        <text text-case="capitalize-first" variable="medium"/>
+      </if>
+      <else-if match="any" type="chapter entry-dictionary entry-encyclopedia paper-conference"/>
+      <else-if variable="URL">
+        <text term="internet" text-case="capitalize-first"/>
+      </else-if>
+    </choose>
+  </macro>
+  <macro name="container-preposition">
+    <choose>
+      <if match="any" type="chapter paper-conference entry-dictionary entry-encyclopedia">
+        <text term="in" text-case="capitalize-first"/>
+      </if>
+    </choose>
+  </macro>
+  <macro name="secondary-authors">
+    <names variable="editor">
+      <label prefix=", "/>
+    </names>
+  </macro>
+  <macro name="container-title">
+    <group delimiter=", ">
+      <choose>
+        <if type="webpage"/>
+        <else-if variable="container-title">
+          <group delimiter=". ">
+            <group delimiter=" ">
+              <choose>
+                <if match="any" type="article-journal review review-book">
+                  <text form="short" strip-periods="true" variable="container-title"/>
+                </if>
+                <else>
+                  <text variable="container-title"/>
+                </else>
+              </choose>
+              <choose>
+                <if type="article-journal" variable="DOI"/>
+                <else-if type="article-journal" variable="PMID"/>
+                <else-if type="article-journal" variable="PMCID"/>
+                <else-if variable="URL">
+                  <text prefix="[" suffix="]" term="internet" text-case="capitalize-first"/>
+                </else-if>
+              </choose>
+            </group>
+            <text macro="label-edition"/>
+          </group>
+        </else-if>
+        <!-- TODO: add `event-name` and `event-place` -->
+        <else-if match="any" type="bill legislation">
+          <group delimiter=". ">
+            <text variable="container-title"/>
+            <group delimiter=" ">
+              <text form="short" term="section" text-case="capitalize-first"/>
+              <text variable="section"/>
+            </group>
+          </group>
+          <text variable="number"/>
+        </else-if>
+        <else-if type="speech">
+          <group delimiter=": ">
+            <group delimiter=" ">
+              <text text-case="capitalize-first" variable="genre"/>
+              <text term="presented at"/>
+            </group>
+            <text variable="event"/>
+          </group>
+        </else-if>
+        <else>
+          <group delimiter=", ">
+            <text macro="label-volume-capitalized"/>
+            <text variable="volume-title"/>
+          </group>
+          <group delimiter=", ">
+            <text macro="label-part-number-capitalized"/>
+            <text variable="part-title"/>
+          </group>
+        </else>
+      </choose>
+    </group>
+  </macro>
+  <macro name="place-of-publication">
+    <choose>
+      <if type="thesis">
+        <text prefix="[" suffix="]" variable="publisher-place"/>
+      </if>
+      <else-if type="speech"/>
+      <else>
+        <text variable="publisher-place"/>
+      </else>
+    </choose>
+  </macro>
+  <macro name="publisher">
+    <choose>
+      <!-- discard publisher for serial publications -->
+      <if match="none" type="article-journal article-magazine article-newspaper periodical post-weblog review review-book">
+        <group delimiter=": ">
+          <text macro="place-of-publication"/>
+          <text variable="publisher"/>
+        </group>
+      </if>
+    </choose>
+  </macro>
+  <macro name="date">
+    <group delimiter=" ">
+      <choose>
+        <if match="any" type="article-journal article-magazine article-newspaper periodical post-weblog review review-book">
+          <group delimiter=":">
+            <group delimiter=" ">
+              <date form="text" variable="issued"/>
+              <choose>
+                <if type="article-journal" variable="DOI"/>
+                <else-if type="article-journal" variable="PMID"/>
+                <else-if type="article-journal" variable="PMCID"/>
+                <else>
+                  <text macro="date-of-citation"/>
+                </else>
+              </choose>
+            </group>
+            <choose>
+              <if type="article-newspaper">
+                <text variable="page"/>
+              </if>
+            </choose>
+          </group>
+        </if>
+        <else-if match="any" type="bill legislation">
+          <date form="text" variable="issued"/>
+        </else-if>
+        <else-if type="report">
+          <date date-parts="year-month" form="text" variable="issued"/>
+          <text macro="date-of-citation"/>
+        </else-if>
+        <else-if type="patent">
+          <group delimiter=", ">
+            <text variable="number"/>
+            <date date-parts="year" form="numeric" variable="issued"/>
+          </group>
+          <text macro="date-of-citation"/>
+        </else-if>
+        <else-if type="speech">
+          <group delimiter="; ">
+            <group delimiter=" ">
+              <date form="text" variable="issued"/>
+              <text macro="date-of-citation"/>
+            </group>
+            <text variable="event-place"/>
+          </group>
+        </else-if>
+        <else>
+          <date date-parts="year" form="numeric" variable="issued"/>
+          <text macro="date-of-citation"/>
+        </else>
+      </choose>
+    </group>
+  </macro>
+  <macro name="identifier-serial">
+    <choose>
+      <if match="any" type="article-journal article-magazine periodical post-weblog review review-book">
+        <group delimiter=":">
+          <group>
+            <text variable="collection-title"/>
+            <text variable="volume"/>
+            <group delimiter=" " prefix="(" suffix=")">
+              <text variable="issue"/>
+              <text macro="label-supplement-number"/>
+            </group>
+          </group>
+          <text macro="location-pagination-serial"/>
+        </group>
+      </if>
+    </choose>
+  </macro>
+  <macro name="date-of-citation">
+    <choose>
+      <if variable="URL">
+        <group delimiter=" " prefix="[" suffix="]">
+          <text term="cited"/>
+          <date form="text" variable="accessed"/>
+        </group>
+      </if>
+    </choose>
+  </macro>
+  <macro name="location-pagination-monographic">
+    <group delimiter=" ">
+      <choose>
+        <if match="any" type="article-journal article-magazine article-newspaper review review-book"/>
+        <else-if type="book">
+          <text macro="label-number-of-pages"/>
+        </else-if>
+        <else>
+          <text macro="label-page"/>
+        </else>
+      </choose>
+    </group>
+  </macro>
+  <macro name="location-pagination-serial">
+    <choose>
+      <if variable="number">
+        <text variable="number"/>
+      </if>
+      <else>
+        <text variable="page"/>
+      </else>
+    </choose>
+  </macro>
+  <macro name="webpage-part">
+    <choose>
+      <if type="webpage" variable="container-title">
+        <text variable="title"/>
+      </if>
+    </choose>
+  </macro>
+  <macro name="series">
+    <choose>
+      <if match="any" type="article-journal article-magazine article-newspaper periodical post-weblog review review-book"/>
+      <else-if variable="collection-title">
+        <group delimiter=". " prefix="(" suffix=")">
+          <names variable="collection-editor">
+            <label prefix=", "/>
+          </names>
+          <group delimiter="; ">
+            <text variable="collection-title"/>
+            <text macro="label-collection-number"/>
+          </group>
+        </group>
+      </else-if>
+    </choose>
+  </macro>
+  <macro name="report-number">
+    <choose>
+      <if type="report" variable="number">
+        <group delimiter=" ">
+          <choose>
+            <if variable="genre">
+              <text text-case="capitalize-first" variable="genre"/>
+            </if>
+            <else>
+              <text term="report" text-case="capitalize-first"/>
+            </else>
+          </choose>
+          <text macro="label-number"/>
+        </group>
+      </if>
+    </choose>
+  </macro>
+  <macro name="availability">
+    <group delimiter=". ">
+      <group delimiter=": ">
+        <text text-case="capitalize-first" value="located at"/>
+        <group delimiter="; ">
+          <group delimiter=", ">
+            <text variable="archive_collection"/>
+            <text variable="archive"/>
+            <text variable="archive-place"/>
+          </group>
+          <text variable="archive_location"/>
+        </group>
+      </group>
+      <group delimiter=" ">
+        <choose>
+          <if type="article-journal" variable="DOI"/>
+          <else-if type="article-journal" variable="PMID"/>
+          <else-if type="article-journal" variable="PMCID"/>
+          <else>
+            <group delimiter=": ">
+              <text term="available at" text-case="capitalize-first"/>
+              <text variable="URL"/>
+            </group>
+          </else>
+        </choose>
+        <text prefix="doi:" variable="DOI"/>
+      </group>
+    </group>
+  </macro>
+  <macro name="notes">
+    <group delimiter=". " suffix=".">
+      <group delimiter="; ">
+        <group delimiter=": ">
+          <text value="PubMed PMID"/>
+          <text variable="PMID"/>
+        </group>
+        <group delimiter=": ">
+          <text value="PubMed Central PMCID"/>
+          <text variable="PMCID"/>
+        </group>
+      </group>
+      <text variable="references"/>
+    </group>
+  </macro>
+  <citation collapse="citation-number">
+    <sort>
+      <key variable="citation-number"/>
+    </sort>
+    <layout delimiter="," prefix="(" suffix=")">
+      <text variable="citation-number"/>
+    </layout>
+  </citation>
+  <macro name="bibliography">
+    <group delimiter=" ">
+      <group delimiter=". " suffix=".">
+        <text macro="author"/>
+        <group delimiter=" ">
+          <text macro="title"/>
+          <text macro="content-type" prefix="[" suffix="]"/>
+          <choose>
+            <if type="webpage" variable="container-title">
+              <text macro="type-of-medium" prefix="[" suffix="]"/>
+            </if>
+            <else-if match="none" variable="container-title">
+              <text macro="type-of-medium" prefix="[" suffix="]"/>
+            </else-if>
+          </choose>
+        </group>
+        <choose>
+          <if match="none" variable="container-title">
+            <text macro="label-edition"/>
+          </if>
+        </choose>
+        <group delimiter=": ">
+          <text macro="container-preposition"/>
+          <group delimiter=". ">
+            <text macro="secondary-authors"/>
+            <text macro="container-title"/>
+          </group>
+        </group>
+        <group delimiter="; ">
+          <text macro="publisher"/>
+          <group delimiter=";">
+            <text macro="date"/>
+            <text macro="identifier-serial"/>
+          </group>
+        </group>
+        <text macro="location-pagination-monographic"/>
+        <text macro="webpage-part"/>
+        <text macro="series"/>
+        <text macro="report-number"/>
+      </group>
+      <text macro="availability"/>
+      <text macro="notes"/>
+    </group>
+  </macro>
+  <bibliography et-al-min="7" et-al-use-first="6" second-field-align="flush">
+    <layout>
+      <text suffix="." variable="citation-number"/>
+      <text macro="bibliography"/>
+    </layout>
+  </bibliography>
+</style>

package/skills/manage-refs/references/REFERENCE_STYLE_SPECS.md

@@ -0,0 +1,59 @@
+# Journal Reference-Style Specs (CSL acceptance criteria)
+
+Zotero-sourced CSL files are **not** auto-validated against each journal's author
+guide. A dependent (stub) CSL inherits its parent's format, which can differ from
+what the journal requires. This table is the **acceptance criteria** for
+`scripts/check_csl_render.py` — run it BEFORE submission so format mismatches are
+caught at build time, not in the portal proof PDF.
+
+## How to use
+
+```bash
+# Validate a CSL against a journal spec before rendering the manuscript:
+python scripts/check_csl_render.py --csl citation_styles/<file>.csl \
+    --bib refs.bib --journal <key>
+# Exits non-zero on mismatch (in-text format / DOI / abbreviation).
+```
+
+If a journal's stub CSL fails (parent format ≠ author guide), create a
+`-strict` variant (see `journal-of-korean-medical-science-strict.csl`) and use it
+for the pandoc render while keeping the original for Zotero CWYW.
+
+## Spec table
+
+| key | Journal | in-text | DOI | journal name | et-al | date | issue | CSL status |
+|-----|---------|---------|-----|--------------|-------|------|-------|-----------|
+| **jkms** | J Korean Med Sci | **superscript** | **none** | **NLM abbrev** | ≤6 then et al | **year only** | include `(n)` | stub→**use `-strict`** ✅ verified 2026-06-03 |
+| radiology | Radiology (RSNA) | paren `(1)` | yes | abbrev | — | — | — | full; ⚠ VERIFY vs author guide |
+| ajr | Am J Roentgenol | superscript | none | abbrev | — | — | — | full; ⚠ VERIFY |
+| kjr | Korean J Radiol | superscript | none | abbrev | — | — | — | full; ⚠ VERIFY |
+| eur-radiol | European Radiology | bracket `[1]` | yes | full ok | — | — | — | stub→springer-basic; ⚠ VERIFY |
+| cvir | Cardiovasc Intervent Radiol | bracket `[1]` | yes | full ok | — | — | — | stub→springer-vancouver; ⚠ VERIFY |
+
+**Legend:** ✅ verified against author guide · ⚠ inherited from Zotero, not yet
+confirmed against the journal's Instructions for Authors. Confirm and update the
+row (and `check_csl_render.py::SPECS`) when you next submit to that journal.
+
+## Known pitfalls (from JKMS submission, 2026-06-03)
+
+1. **Journal abbreviation needs metadata.** CSL `container-title form="short"` only
+   works if the `.bib` entry has a `shortjournal` (BibLaTeX) / `journalAbbreviation`
+   (Zotero) field. Without it, the full name is printed regardless of CSL. Use
+   `scripts/fill_journal_abbrev.py` to populate NLM abbreviations from PubMed.
+2. **Title proper nouns.** pandoc/citeproc applies sentence-case to titles and will
+   lowercase proper nouns (`Fleischner Society` → `fleischner society`) unless the
+   title is double-braced `title = {{...}}`. Pull authoritative titles (with
+   subtitle + proper-noun casing) from PubMed efetch ArticleTitle.
+3. **Name particles.** `de Torres`, `von Elm`, `de Bock` get demoted to
+   `Torres JP de` unless braced `{de Torres}` in the family field. `demote-non-dropping-particle="never"`
+   alone is insufficient because citeproc auto-splits lowercase particles.
+4. **DOI hyperlinks survive surgical docx edits.** If you swap reference text in a
+   Word file, a `<w:hyperlink>` carrying the DOI persists as a separate element
+   (python-docx `p.runs` doesn't see it). Remove hyperlinks explicitly. See
+   `~/.claude/rules/submission-portal-verification.md` §1.
+
+## Related
+- `scripts/check_csl_render.py` — acceptance test
+- `scripts/fill_journal_abbrev.py` — NLM abbreviation injection
+- `citation_styles/journal-of-korean-medical-science-strict.csl` — JKMS author-guide-faithful variant
+- `~/.claude/rules/manuscript-references.md` — hybrid pandoc/Zotero workflow

package/skills/manage-refs/references/check_xref_symptoms.md

@@ -0,0 +1,35 @@
+# Cross-reference QC — symptom triage
+
+`check_xref.py --strict` writes a 3-way matrix to `qc/xref_audit.json` that
+classifies every Table/Figure label across (a) in-text citations, (b) body
+captions in `## Tables` / `## Figures` / `## Figure Legends` /
+`## Supplementary {Tables,Figures}`, and (c) caption paragraphs in the
+rendered DOCX (via `python-docx`).
+
+| Status | Meaning | Severity | Fix |
+|---|---|---|---|
+| `OK` | cited + body caption + DOCX caption all present, caption text agrees (Jaccard ≥ 0.40) | — | none |
+| `MISSING_DOCX` | cited but no caption with that label in the rendered DOCX | **P0 blocker** | drop the citation if the figure/table was retired, or re-add it to the build pipeline and rebuild DOCX |
+| `MISSING_BODY` | cited but no caption definition in the markdown body sections (build SSOT drift) | **P0 blocker** | add the caption under `## Tables` / `## Figures` in `manuscript.md`, then re-render |
+| `MISMATCH` | label exists in both body and DOCX but caption text disagrees (Jaccard < 0.40) | **P0 blocker** | reconcile body vs build script — body caption is the SSOT, update the build pipeline to match, never the reverse |
+| `UNCITED` | caption defined or rendered but never cited in main text | warn | either delete the caption or add a citation; never ship UNCITED on a clean run |
+| `NOT_CITED_NO_BODY` | label appears only in DOCX (rare; legacy artifact) | warn | clean up the build pipeline; the DOCX is leaking captions from a previous draft |
+
+## Why this exists
+
+Internal consistency in `/self-review` Phase 2.5 does NOT catch
+cross-reference defects because both the body prose and the build script
+can echo their own divergent SSOTs cleanly — each looks self-consistent in
+isolation. Precedent: an STROBE cohort manuscript revision — body cited
+"Supplementary Table S4 (a sensitivity-analysis)" but the rendered DOCX S4 was
+a diagnostics table; S1, S6, S7 mismatched and S8, S9 were cited but absent
+from the DOCX entirely. The 3-way matrix between citations, body captions,
+and DOCX captions is the only place those drifts surface.
+
+## Pipeline placement
+
+Always run **after** the DOCX build (Workflow A step 2 or after
+`render_pandoc.sh`) and **before** the final submission gate. If
+`python-docx` is unavailable, the script falls back to a body-only audit
+(citations vs body captions) with a stderr warning; install with
+`pip install python-docx` for full coverage.