medsci-skills 5.13.0 → 5.15.0

package/README.md

@@ -2,14 +2,14 @@
 
 # MedSci Skills
 
-**51 skills that actually work.** Built by a physician-researcher, tested on real publications.
+**53 skills that actually work.** Built by a physician-researcher, tested on real publications.
 
 *MedSci Skills is an end-to-end research tool for physician and medical-engineering researchers — design → scaffold → validate → publish — for the clinical manuscript and the medical-AI model behind it. Its moat is the compliance layer — 44 reporting guidelines and risk-of-bias tools, reference/citation verification, and deterministic integrity gates before peer review — now extended by a model-engineering lane that scaffolds reproducible, leakage-safe training repos and audits model validation. Clinical AI model research engineering is in scope; a general AI-scientist platform is not. It competes on clinical submission reliability, not skill count.*
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Release](https://img.shields.io/github/v/release/Aperivue/medsci-skills?style=flat-square&color=blue)](https://github.com/Aperivue/medsci-skills/releases/latest)
 [![CI](https://img.shields.io/github/actions/workflow/status/Aperivue/medsci-skills/validate.yml?branch=main&style=flat-square&label=CI)](https://github.com/Aperivue/medsci-skills/actions/workflows/validate.yml)
-![Skills](https://img.shields.io/badge/Skills-51-brightgreen?style=flat-square)
+![Skills](https://img.shields.io/badge/Skills-53-brightgreen?style=flat-square)
 [![npm](https://img.shields.io/npm/v/medsci-skills?style=flat-square&label=npm&color=cb3837)](https://www.npmjs.com/package/medsci-skills)
 [![Watch the 2-min intro](https://img.shields.io/badge/▶_Watch-2--min_intro-FF0000?style=flat-square&logo=youtube&logoColor=white)](https://youtu.be/MclQ_RIofpE)
 [![good first issues](https://img.shields.io/github/issues/Aperivue/medsci-skills/good%20first%20issue?style=flat-square&label=good%20first%20issues&color=7057ff)](https://github.com/Aperivue/medsci-skills/contribute)
@@ -285,6 +285,8 @@ The E2E pipeline (`orchestrate --e2e`) produces everything up to `qc/`. The `sub
 
 ## What's New
 
+**v5.15** — model-engineering produce-side depth. Two new skills that *produce* what the review lane previously only audited: **`preprocess-imaging`** (DICOM/NIfTI data prep + a `check_preprocessing_leakage` gate that extends the split-leakage moat upstream to the data stage) and **`explainability`** (Grad-CAM / saliency held to the reviewer bar — Adebayo sanity checks, quantitative localisation vs ground truth, attribution-not-validation framing, via `check_explainability_report`). Plus a by-stage skill index, multi-host README/About (Claude Code · Codex · Cursor · Copilot), copy-paste citation ergonomics, and a real-project precision fix. Additive and backward-compatible; **53 skills / 44 guidelines / 48 integrity detectors / 22 domain-probe modules**. (See the [CHANGELOG](CHANGELOG.md) for v5.0–v5.14.)
+
 **v4.10** — reviewer-coverage expansion reverse-engineered from high-IF, CC-BY papers (learn-only under the `reverse_engineer/` license firewall), plus a clinician-friendly update path. Additive and backward-compatible; 45 skills / **44 guidelines** / 36 detectors / **15 domain-probe modules** (was 12):
 
 - **Three new reviewer domain-probe modules** (`/peer-review` + `/self-review`, vendored byte-identical): **Mendelian randomization** (MR1–MR8 — IV assumptions, pleiotropy-robust sensitivity suite, Steiger, sample overlap, NLMR, drug-target colocalization), **polygenic risk score** (PG1–PG8 — ancestry portability, base/target leakage, incremental value over the clinical model, screening-vs-discrimination, calibration), and **network meta-analysis** (NM1–NM8 — transitivity, incoherence, SUCRA over-interpretation, CINeMA/GRADE-NMA, component-NMA additivity). Plus observational **O17** (agnostic many-exposure-scan multiplicity: ExWAS/EWAS/MWAS).
@@ -447,6 +449,21 @@ ma-scout -> search-lit -> fulltext-retrieval -> design-study ──> write-proto
                               └─────────────────────────────────────────────┘
 ```
 
+### By research stage
+
+All 53 skills, grouped by where they fit in the clinical-manuscript and medical-AI lifecycle. Full descriptions are in the table below; one page per skill lives in the [per-skill reference](docs/skills/).
+
+| Stage | Skills |
+|-------|--------|
+| 🔭 **Discover & scope** | `ma-scout` · `find-cohort-gap` · `search-lit` · `fulltext-retrieval` · `lit-sync` · `author-strategy` |
+| 📐 **Design & plan** | `design-study` · `calc-sample-size` · `define-variables` · `write-protocol` · `fill-protocol` · `design-ai-benchmarking` |
+| 🧹 **Data & analysis** | `deidentify` · `clean-data` · `generate-codebook` · `version-dataset` · `analyze-stats` · `batch-cohort` · `cross-national` · `replicate-study` |
+| 🤖 **Medical-AI model engineering** | `preprocess-imaging` · `architecture-zoo` · `model-scaffold` · `model-validation` · `model-evaluation` · `explainability` · `model-card` · `mllm-eval` |
+| ✍️ **Write & visualize** | `write-paper` · `make-figures` · `review-paper` · `present-paper` · `humanize` · `polish-language` · `academic-aio` |
+| ✅ **Comply & verify** | `check-reporting` · `self-review` · `verify-refs` · `manage-refs` |
+| 📤 **Submit & respond** | `find-journal` · `add-journal` · `sync-submission` · `revise` · `peer-review` · `fill-icmje-coi` |
+| 🧭 **Orchestrate & manage** | `orchestrate` · `intake-project` · `manage-project` · `meta-analysis` · `grant-builder` · `publish-skill` · `render-pdf-doc` · `setup-medsci` |
+
 ### Available Now
 
 | Skill | What It Does |
@@ -463,10 +480,12 @@ ma-scout -> search-lit -> fulltext-retrieval -> design-study ──> write-proto
 | **design-study** | Study design review: identifies analysis unit, cohort logic, data leakage risks, comparator design, validation strategy, and reporting guideline fit. |
 | **design-ai-benchmarking** | Design and validity review for benchmarking AI system(s) against a human-expert panel: evaluation-question and arm definition, decoupled multi-dimensional rubrics with anchors, planted calibration probes (positive-control / known-bad / instability / mechanism-contradiction), reviewer-panel construction with per-reviewer randomization, inter-rater reliability targets with separate control-item reliability, LLM-as-judge vs human-as-judge adjudication, construct-independence guards, and a structured JSON rating-export schema. Locks the rubric before data collection. |
 | **model-validation** | Design or audit the clinical-validation study for an engineer-built medical-imaging model (segmentation / classification / detection): patient-level split disjointness and the data-leakage taxonomy, tuning-on-test, internal vs genuine external validation, comparator design, single-run vs multi-seed variance, task-correct metric selection (Metrics Reloaded), test-set sizing, and CLAIM 2024 / TRIPOD+AI / STARD-AI reporting fit. Ships a deterministic split-leakage gate that proves patient disjointness by set arithmetic on the emitted split table. Integrates with MONAI / nnU-Net — does not replace them. |
+| **preprocess-imaging** | Design or audit the data-preparation stage of a medical-imaging model — DICOM/NIfTI intake, resampling, intensity normalization, and the augmentation plan — so the pipeline is leakage-safe before `model-scaffold` builds the training repo. Emits a declarative preprocessing manifest and a deterministic data-stage leakage gate (`check_preprocessing_leakage`) that catches what the split table cannot see: a dataset-level normaliser fit on non-train data (`NORMALIZATION_LEAKAGE`), a data-fitted transform run before the split (`PREPROCESS_BEFORE_SPLIT`), and a patient's slices crossing splits (`PATIENT_CROSS_SPLIT`). Integrates MONAI / TorchIO transforms; never reimplements them or touches real patient data. |
 | **model-scaffold** | Generate a reproducible, runnable PyTorch training repo for a medical-imaging task — segmentation (U-Net), classification, detection, image-to-image synthesis, or self-supervised pretraining — the missing middle link between choosing an architecture and validating a trained model. Emits a patient-level seed-locked split as an auditable artifact, a task-appropriate model, train/evaluate scripts that seed every RNG and infer under eval mode, a config, requirements, a reproducibility record, and a Methods stub with VERIFY placeholders (no fabricated numbers). Reproducibility holds by construction; ships a `check_training_hygiene` AST gate + a network-free build→validate challenge. Emits a minimal runnable default model for a forward-pass smoke test, and integrates with MONAI / nnU-Net / TorchIO / timm / torchvision for production-grade models. |
 | **architecture-zoo** | "Which architecture for which research question" decision tool: maps task (classification / segmentation / detection / transfer), modality, data scale, and class imbalance to a paper-grounded architecture shortlist. Curates the foundational curriculum (ResNet / DenseNet / EfficientNet / ViT / Swin; U-Net / 3-D U-Net / Attention & Residual U-Net / nnU-Net / Mask R-CNN; SAM/MedSAM / TotalSegmentator / BiomedCLIP / DINO / MAE / SimCLR) — each with core idea, when-to-use, medical-imaging use, reference implementation, validation setup, and the matching model-scaffold template. Advisory; teaches archetypes, not a live SOTA leaderboard. |
 | **model-card** | Generate the documentation an engineer-built medical-imaging model must carry — a Model Card (Mitchell et al. 2019), a Datasheet for its dataset (Gebru et al. 2021), and a METRIC-informed data-quality pass — filled from user-supplied facts (never fabricated), then verify every required section is present and non-empty with a deterministic completeness gate (`check_model_card_complete`). Model Card / Datasheet are documentation standards vendored as templates, not counted reporting checklists. |
 | **model-evaluation** | Compute and report task-correct held-out metrics for a trained medical-imaging model — segmentation (Dice + a boundary metric HD95/NSD, per structure), classification (AUROC + AUPRC + sensitivity/specificity with bootstrap CIs at the deployment prevalence), or detection (FROC/mAP with a stated IoU criterion) — plus calibration and subgroup slices. Emits a per-case table for analyze-stats and gates the metric choice against Metrics Reloaded / CLAIM 2024 (`check_metric_reporting`). Numbers come only from executed code. |
+| **explainability** | Produce or audit the interpretability/explainability analysis of a medical-imaging model — Grad-CAM / Grad-CAM++ / attention-rollout / saliency / integrated-gradients — so it clears the rigor bar: mandatory Adebayo sanity checks (model- and data-randomisation), a quantitative localisation metric against ground truth (IoU / pointing game / Dice) instead of eyeballed examples, a cohort-level result, and attribution framing rather than "proof the model is correct". Emits an explainability-report manifest + a deterministic gate (`check_explainability_report`): `SALIENCY_AS_VALIDATION`, `NO_SANITY_CHECK`, `NO_LOCALIZATION_METRIC` (Major); `INSUFFICIENT_SANITY`, `CHERRY_PICKED_EXAMPLES`, `MISSING_METHOD` (Minor). Integrates captum / pytorch-grad-cam; never reimplements them or touches real patient data. |
 | **mllm-eval** | Model-agnostic evaluation harness (closed API or open weights) for an LLM/MLLM on a clinical task — radiology report generation, VQA, clinical text extraction — covering the adjudicated reference standard, clinical-efficacy metrics (RadGraph-F1 / CheXbert-F1 beyond BLEU/ROUGE), faithfulness/hallucination, pretraining-contamination, prompt sensitivity, and a reader study; gates the plan with `check_mllm_eval_completeness` and routes the reviewer audit to the MLLM probe. |
 | **intake-project** | Classifies new research projects, summarizes current state, identifies missing inputs, and recommends next steps. |
 | **grant-builder** | Structures grant proposals: significance, innovation, approach, milestones, and consortium roles. |
@@ -787,15 +806,44 @@ It helps other researchers find the toolkit — and we list it (with your permis
 
 ## Citation
 
-If you use MedSci Skills in your research, please cite the software via
-[`CITATION.cff`](CITATION.cff) (Zenodo concept DOI
-[10.5281/zenodo.20155321](https://doi.org/10.5281/zenodo.20155321)).
+If MedSci Skills helped produce your manuscript, protocol, or analysis, please cite it —
+software citation is how a tool like this earns academic recognition, and it takes one line.
 
-The design and evaluation of the toolkit are described in a preprint:
+**In your manuscript** (Methods or Acknowledgements — cite the version you actually used):
 
-> Nam Y, Kim N. *Agentic Skills for Auditable and Reproducible Medical Research
-> Writing: An Integrity-gated Architecture for LLM-Assisted Clinical Manuscripts.*
-> arXiv:2606.09500 (2026). https://arxiv.org/abs/2606.09500
+> Reporting-guideline compliance, reference verification, and pre-submission integrity checks
+> were assisted by MedSci Skills (version X.Y.Z; https://github.com/Aperivue/medsci-skills;
+> archived at Zenodo, https://doi.org/10.5281/zenodo.20155321).
+
+**BibTeX** (the software, and the preprint describing its design):
+
+```bibtex
+@software{nam_medsci_skills,
+  author    = {Nam, Yoojin},
+  title     = {{MedSci Skills: Claude Code Skills for the Medical Research Lifecycle}},
+  year      = {2026},
+  publisher = {Zenodo},
+  doi       = {10.5281/zenodo.20155321},
+  url       = {https://github.com/Aperivue/medsci-skills}
+}
+
+@article{nam2026agentic,
+  author  = {Nam, Yoojin and Kim, Namkug},
+  title   = {{Agentic Skills for Auditable and Reproducible Medical Research Writing:
+             An Integrity-gated Architecture for LLM-Assisted Clinical Manuscripts}},
+  year    = {2026},
+  journal = {arXiv preprint arXiv:2606.09500},
+  url     = {https://arxiv.org/abs/2606.09500}
+}
+```
+
+The Zenodo **concept DOI** [10.5281/zenodo.20155321](https://doi.org/10.5281/zenodo.20155321)
+always resolves to the latest release; [`CITATION.cff`](CITATION.cff) carries the machine-readable
+metadata (GitHub's "Cite this repository" button reads it).
+
+**Used it in published or in-review work?** Tell us via the
+["Used in research" issue template](https://github.com/Aperivue/medsci-skills/issues/new?template=used-in-research.yml)
+— with your permission it is added to [`docs/citations.md`](docs/citations.md).
 
 ## Disclaimer
 
@@ -815,8 +863,16 @@ Bundled reporting guideline checklists retain their original Creative Commons li
 
 Optional dependency: `pdf_to_md.py` uses [pymupdf4llm](https://pymupdf.readthedocs.io) (AGPL-3.0). Not bundled -- installed separately by the user via `pip install pymupdf4llm`.
 
+## Star History
+
+<a href="https://star-history.com/#Aperivue/medsci-skills&Date">
+  <img src="https://api.star-history.com/svg?repos=Aperivue/medsci-skills&type=Date" alt="MedSci Skills star history" width="640">
+</a>
+
 ## About
 
 Built by [Aperivue](https://aperivue.com) -- tools for medical AI research and education.
 
+**Runs anywhere the [Agent Skills standard](https://agentskills.io) is supported** -- not Claude Code alone. Claude Code, OpenAI Codex, Cursor, and GitHub Copilot are all verified against each host's own docs: one install, four hosts, no per-host fork ([host compatibility](docs/host_compatibility.md)).
+
 If you find this useful, consider giving it a star. It helps other researchers discover these tools.

package/metadata/distribution_files.json

@@ -153,14 +153,19 @@
     },
     {
       "path": "skills/analyze-stats/SKILL.md",
-      "size": 56422,
-      "sha256": "ddb73598fe60601942e8b44a87771e3ba583a585304effac4ae206d53ab4f154"
+      "size": 56948,
+      "sha256": "e7f01164e2fc9db924e49ee226b13bcf78d4d7c0463099c0f666985152a91d2e"
     },
     {
       "path": "skills/analyze-stats/references/analysis_guides/agreement_reliability.md",
       "size": 6674,
       "sha256": "599ad2551f547043b2bec79e3139d9c2c3ae33c5025784359b22022f882504c2"
     },
+    {
+      "path": "skills/analyze-stats/references/analysis_guides/calibration.md",
+      "size": 6470,
+      "sha256": "ac33862c6c707997be5a2511ed6a6d546c1e829fc9fc033d1c85eca9afa3ca9a"
+    },
     {
       "path": "skills/analyze-stats/references/analysis_guides/diagnostic_accuracy.md",
       "size": 9303,
@@ -1076,6 +1081,56 @@
       "size": 1411,
       "sha256": "3981d5da7734b90e6905ac329e996b145af82bd6a28ec2a8d42918e9ce077ee5"
     },
+    {
+      "path": "skills/explainability/SKILL.md",
+      "size": 6474,
+      "sha256": "4d1c082ad48393adb65203ffbedf63f772fdc521d873f657cbfc81150c7b36de"
+    },
+    {
+      "path": "skills/explainability/references/explainability_guide.md",
+      "size": 4203,
+      "sha256": "24bc06181e54801b148f142f9312fe0eede9f540a4e57810701506681e254b4b"
+    },
+    {
+      "path": "skills/explainability/scripts/check_explainability_report.py",
+      "size": 10783,
+      "sha256": "4071a93aacf509f73a44b2c7f6423b5722aab3d44c79e9a8680845454261d47d"
+    },
+    {
+      "path": "skills/explainability/scripts/check_explainability_report_challenge/expected/strong.txt",
+      "size": 391,
+      "sha256": "317018eb7546f77b2de39ff1b73c9e82584a9d65c25eb91a940de76a4c7d2ec5"
+    },
+    {
+      "path": "skills/explainability/scripts/check_explainability_report_challenge/expected/weak.txt",
+      "size": 876,
+      "sha256": "de5c090c1ee4c632d7d59bc0d5f20fac8d28342b74b68eb51066677658245451"
+    },
+    {
+      "path": "skills/explainability/scripts/check_explainability_report_challenge/fixture/report_strong.json",
+      "size": 238,
+      "sha256": "b835871c1d98313f736575faf7f6adbb5cfabe4e3dfd1abe1279976c8c5f1867"
+    },
+    {
+      "path": "skills/explainability/scripts/check_explainability_report_challenge/fixture/report_weak.json",
+      "size": 163,
+      "sha256": "dfde5db357a83660f941fdde957bb3a9af25f60d26300322f04b3981b13c429a"
+    },
+    {
+      "path": "skills/explainability/scripts/check_explainability_report_challenge/problem.md",
+      "size": 805,
+      "sha256": "1b667c138ac54e38614e438efdb995adba208588007e95eed6f374233ff6dcdc"
+    },
+    {
+      "path": "skills/explainability/scripts/check_explainability_report_challenge/verify.sh",
+      "size": 2005,
+      "sha256": "5246897dc616e04fa1260e9b20d9970e1499f95ebb52034bba59482d401c1156"
+    },
+    {
+      "path": "skills/explainability/skill.yml",
+      "size": 3569,
+      "sha256": "5b3e135825470392867dc851627d9899bc512d9a5ee52556c205eea8fae4edb1"
+    },
     {
       "path": "skills/fill-icmje-coi/SKILL.md",
       "size": 9997,
@@ -3053,8 +3108,8 @@
     },
     {
       "path": "skills/peer-review/references/domain-probes/survival_prognostic.md",
-      "size": 14022,
-      "sha256": "96195cd1b575535bc12a133125b9d85e2ca7e756b96a0649e03d4c3696e5312b"
+      "size": 14297,
+      "sha256": "32cd929ff2e151f33bc5b106eddef0d38d5bd15672054e690c603ee82a22a817"
     },
     {
       "path": "skills/peer-review/references/exemplar_reviews/README.md",
@@ -3176,6 +3231,56 @@
       "size": 1753,
       "sha256": "ce4996820b24c230584890c501860c8d37dfd07521195954077d2fdd1a26f419"
     },
+    {
+      "path": "skills/preprocess-imaging/SKILL.md",
+      "size": 7068,
+      "sha256": "e17b73b0760194d4e6e3924ec2a0452601adc27122e7455cc5f2993d5af1d0d0"
+    },
+    {
+      "path": "skills/preprocess-imaging/references/preprocessing_guide.md",
+      "size": 5023,
+      "sha256": "fdab6d435ff6bce7b6787319acda9b0b160411bc2e1109e15154bbb8a68c8282"
+    },
+    {
+      "path": "skills/preprocess-imaging/scripts/check_preprocessing_leakage.py",
+      "size": 12992,
+      "sha256": "dcce1493a29122ed4259adc116ed7ad239b11ee1f45a10f6f7eb94698b3efa67"
+    },
+    {
+      "path": "skills/preprocess-imaging/scripts/check_preprocessing_leakage_challenge/expected/clean.txt",
+      "size": 370,
+      "sha256": "bc1efcfc1d8575d78a0448752e60a3b58d654a5bc1a7b11360e4d9ba690665ac"
+    },
+    {
+      "path": "skills/preprocess-imaging/scripts/check_preprocessing_leakage_challenge/expected/leak.txt",
+      "size": 1030,
+      "sha256": "fe046c81f20b34a6ff3fd6858f7832e786106ed56635b39f7e413b4853d4b7e8"
+    },
+    {
+      "path": "skills/preprocess-imaging/scripts/check_preprocessing_leakage_challenge/fixture/manifest_clean.json",
+      "size": 800,
+      "sha256": "e01ff6d09aae6f76d3b2b1cd05c333d66fd53499a2a2d1296380eefde720c515"
+    },
+    {
+      "path": "skills/preprocess-imaging/scripts/check_preprocessing_leakage_challenge/fixture/manifest_leak.json",
+      "size": 881,
+      "sha256": "a55389654128c577e16eefb3c6b8f85d8a47bdc06a817619f13036a1e1ebe4b4"
+    },
+    {
+      "path": "skills/preprocess-imaging/scripts/check_preprocessing_leakage_challenge/problem.md",
+      "size": 903,
+      "sha256": "042ddd4736133ccf63192ea65c4faa714b2854ec9bb704f29ca2f401cd4658ee"
+    },
+    {
+      "path": "skills/preprocess-imaging/scripts/check_preprocessing_leakage_challenge/verify.sh",
+      "size": 2188,
+      "sha256": "9201d264720627f7281f43bcf3b1093bf6940f67acd7c299c8b3ac64fb58b564"
+    },
+    {
+      "path": "skills/preprocess-imaging/skill.yml",
+      "size": 3518,
+      "sha256": "c6edc7ac6421438d4e0b64cd416202ac9f91092870ea1cb8531ba15fda7d5c72"
+    },
     {
       "path": "skills/present-paper/SKILL.md",
       "size": 33518,
@@ -3613,8 +3718,8 @@
     },
     {
       "path": "skills/self-review/references/domain-probes/survival_prognostic.md",
-      "size": 14022,
-      "sha256": "96195cd1b575535bc12a133125b9d85e2ca7e756b96a0649e03d4c3696e5312b"
+      "size": 14297,
+      "sha256": "32cd929ff2e151f33bc5b106eddef0d38d5bd15672054e690c603ee82a22a817"
     },
     {
       "path": "skills/self-review/references/exemplar_findings/README.md",
@@ -3753,8 +3858,8 @@
     },
     {
       "path": "skills/self-review/scripts/check_scope_coherence.py",
-      "size": 11920,
-      "sha256": "e600e54fcbe308060a8dadd871ec274b6ae19f89456ae0194490e152c0d09a91"
+      "size": 12989,
+      "sha256": "2444bce9c5bd2fc088c43eae97c1fc5791ae4da44f428a2caa0559b976dbe622"
     },
     {
       "path": "skills/self-review/scripts/check_supplement_hygiene.py",
@@ -3918,8 +4023,8 @@
     },
     {
       "path": "skills/write-paper/SKILL.md",
-      "size": 66771,
-      "sha256": "1a50c9ceb040a79feaa60e809c7196f9f04b85cab2f5f3402dcaed3f7aee552c"
+      "size": 67054,
+      "sha256": "62b3cbff56a139ed20a783c462fb6dde6b7a932bb057762a2d1c6382c8d044c1"
     },
     {
       "path": "skills/write-paper/references/exemplar_abstract.md",
@@ -3938,8 +4043,8 @@
     },
     {
       "path": "skills/write-paper/references/exemplar_discussion/README.md",
-      "size": 2727,
-      "sha256": "3bfcd4eb4df4ca0309446a606550cb11adc4d88daa676f2217249691d2e6b042"
+      "size": 2902,
+      "sha256": "1db58e8d3801a7fd2bd6a6bb9c271f22436a71e82ba034a8c888e9468945a026"
     },
     {
       "path": "skills/write-paper/references/exemplar_discussion/ai_validation_tripod_claim.md",
@@ -3961,6 +4066,11 @@
       "size": 3652,
       "sha256": "21ec3cbfcb626cc00f09e66aa27d8f2f835a202ed083bcebcba57b787ddff866"
     },
+    {
+      "path": "skills/write-paper/references/exemplar_discussion/rct_consort.md",
+      "size": 2613,
+      "sha256": "2fa6e9f621219974f07294e8637da83d923327207e38e1692b62bb45c7d20ab5"
+    },
     {
       "path": "skills/write-paper/references/exemplar_introduction.md",
       "size": 2636,
@@ -3968,8 +4078,8 @@
     },
     {
       "path": "skills/write-paper/references/exemplar_methods/README.md",
-      "size": 2342,
-      "sha256": "6966e8b723d0c4ccc012d54e2b8a22ef59b39c22619e63a8597f9badb380b4e7"
+      "size": 2426,
+      "sha256": "b55addd809841fdb8ae8e834693c7a03602cb1d8aeb00131ed86ecb8fbc713f6"
     },
     {
       "path": "skills/write-paper/references/exemplar_methods/ai_validation_tripod_claim.md",
@@ -3991,10 +4101,15 @@
       "size": 2364,
       "sha256": "e2ea3f64be321d2fb8249d4d528cfd24231c0b69d2562e4290cf3dcddd29d419"
     },
+    {
+      "path": "skills/write-paper/references/exemplar_methods/rct_consort.md",
+      "size": 3268,
+      "sha256": "742e343b163336a6dda2fa2054e0f486df489e1d6cb2cf3eb782e05d25d9710d"
+    },
     {
       "path": "skills/write-paper/references/exemplar_results/README.md",
-      "size": 2799,
-      "sha256": "14b588f1f4433be71c39f11627148fff797eb87b3b74be75e61514095d4c38ea"
+      "size": 2989,
+      "sha256": "b67ec682f899a1774af10913eaeb8f33956859da2ef787250c01ef3b437f1155"
     },
     {
       "path": "skills/write-paper/references/exemplar_results/ai_validation_tripod_claim.md",
@@ -4016,6 +4131,11 @@
       "size": 2452,
       "sha256": "4c8e1fc5c5d00a3c0dc26ea0d94dc80e3077a96503ada653ccdcee8eeb8b14da"
     },
+    {
+      "path": "skills/write-paper/references/exemplar_results/rct_consort.md",
+      "size": 2356,
+      "sha256": "6a0becfe8f24db7f686bd23f26c9caec749dd996914705679ea915398fc7c3dd"
+    },
     {
       "path": "skills/write-paper/references/journal_profiles/AJNR.md",
       "size": 6381,

package/metadata/distribution_manifest.json

@@ -1,6 +1,6 @@
 {
   "schema_version": 1,
-  "version": "5.13.0",
+  "version": "5.15.0",
   "owned_skills": [
     "academic-aio",
     "add-journal",
@@ -16,6 +16,7 @@
     "deidentify",
     "design-ai-benchmarking",
     "design-study",
+    "explainability",
     "fill-icmje-coi",
     "fill-protocol",
     "find-cohort-gap",
@@ -39,6 +40,7 @@
     "orchestrate",
     "peer-review",
     "polish-language",
+    "preprocess-imaging",
     "present-paper",
     "publish-skill",
     "render-pdf-doc",

package/metadata/skills_catalog.json

@@ -1,6 +1,6 @@
 {
   "_comment": "AUTO-GENERATED by scripts/gen_skills_catalog_json.py from each skills/<slug>/SKILL.md + skill.yml. Machine-readable skill catalog (single source of truth) consumed by external surfaces such as the aperivue.com storefront to gate skill-list completeness. Do not hand-edit; CI gate: python3 scripts/gen_skills_catalog_json.py --check.",
-  "skill_count": 51,
+  "skill_count": 53,
   "categories": [
     {
       "key": "literature_references",
@@ -32,11 +32,13 @@
       "label": "Model Engineering & Validation",
       "slugs": [
         "architecture-zoo",
+        "explainability",
         "mllm-eval",
         "model-card",
         "model-evaluation",
         "model-scaffold",
-        "model-validation"
+        "model-validation",
+        "preprocess-imaging"
       ]
     },
     {
@@ -235,6 +237,15 @@
       "maturity": "official",
       "description": "Study design and validity review for radiology and medical AI research."
     },
+    {
+      "slug": "explainability",
+      "category": "model_engineering",
+      "category_label": "Model Engineering & Validation",
+      "layer": "D",
+      "owner_domain": "model_validation",
+      "maturity": "official",
+      "description": "Produce or audit the interpretability/explainability analysis of a medical-imaging model — Grad-CAM / Grad-CAM++ / attention-rollout / saliency / integrated-gradients — so it clears the rigor bar a re…"
+    },
     {
       "slug": "fill-icmje-coi",
       "category": "submission_journals",
@@ -442,6 +453,15 @@
       "maturity": "official",
       "description": "Academic English consistency linting and non-native (ESL) language polish for medical manuscripts."
     },
+    {
+      "slug": "preprocess-imaging",
+      "category": "model_engineering",
+      "category_label": "Model Engineering & Validation",
+      "layer": "D",
+      "owner_domain": "model_validation",
+      "maturity": "official",
+      "description": "Design or audit the data-preparation stage of a medical-imaging model — DICOM/NIfTI intake, resampling and intensity normalisation, and the augmentation plan — so the pipeline is leakage-safe before m…"
+    },
     {
       "slug": "present-paper",
       "category": "presentation_tooling",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "medsci-skills",
-  "version": "5.13.0",
+  "version": "5.15.0",
   "description": "MedSci Skills — a medical/scientific research skill suite for AI coding agents (Claude Code, Codex, Cursor, Copilot). The npm package is a terminal-friendly installer shortcut; the canonical distribution remains the GitHub repository and the Claude Code plugin marketplace.",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://github.com/Aperivue/medsci-skills#readme",

package/skills/analyze-stats/SKILL.md

@@ -545,7 +545,8 @@ When death or other events preclude the outcome of interest, standard KM overest
 - **Guide**: Load `analysis_guides/regression.md` before generating code
 - **Template**: `references/templates/regression.py` (set `regression_type = "logistic"`)
 - Run univariable analysis first, then multivariable with clinically selected variables
-- Required outputs: OR table (univariable + multivariable), C-statistic (95% CI), Hosmer-Lemeshow
+- Required outputs: OR table (univariable + multivariable), C-statistic (95% CI), and **calibration** (intercept + slope + flexible plot — **not** Hosmer–Lemeshow, which is deprecated; see the calibration guide)
+- **Prediction-model calibration guide**: `references/analysis_guides/calibration.md` (**load before generating code** for any model that outputs a risk used for a decision — the apparent slope of exactly 1.00 is the in-sample tell, so produce the **bootstrap optimism-corrected** slope/intercept; Van Calster's calibration levels; scaled Brier; why Hosmer–Lemeshow is dropped; produce-side of probe S7)
 - Check VIF < 5, EPV >= 10 (warn if violated)
 - **Nested observation units**: when rows are clustered within subjects (multiple lesions/visits per patient), use cluster-robust standard errors (`cov_type="cluster"`, `cov_kwds={"groups": id}` in statsmodels) or a mixed-effects logistic model — a naive logit CI assumes independent rows and is too narrow
 - Box-Tidwell test for continuous predictor linearity

package/skills/analyze-stats/references/analysis_guides/calibration.md

@@ -0,0 +1,132 @@
+# Prediction-Model Calibration Guide
+
+For a clinical prediction model (a logistic risk score or a Cox/survival model at a fixed
+horizon), **discrimination (AUC / C-index) is not enough** — a model that ranks well can still
+output probabilities that are systematically too high or too low. The ways calibration fails
+review are (1) reporting **apparent (in-sample)** calibration — a slope of exactly 1.00 is the
+fingerprint — with no internal-validation correction, (2) leaning on the **Hosmer–Lemeshow**
+test (deprecated), and (3) omitting calibration entirely for a model meant to guide care. This
+guide produces the corrected estimand; it is the produce-side of probe **S7**.
+
+---
+
+## When to Use
+
+- Any model that outputs a **risk / probability** used for a decision (surveillance intensity,
+  treatment eligibility, triage) — logistic or survival-at-a-horizon.
+- Reported **alongside** discrimination and, for a utility claim, decision-curve net benefit —
+  never discrimination alone.
+- NOT a substitute for external validation: internal (bootstrap/CV) calibration corrects
+  optimism but does not establish transportability.
+
+---
+
+## Apparent calibration is optimistic — correct it (this is the S7 issue)
+
+Fit a logistic model by maximum likelihood and its **apparent** calibration slope on the same
+data is **exactly 1.00** and its calibration-in-the-large intercept **exactly 0** — by
+construction, not because the model is well-calibrated. A slope printed as `1.00` (or metrics
+with no `bootstrap` / `cross-valid` / `optimism` / `held-out` token nearby) is presumptively
+in-sample. Produce the **bootstrap optimism-corrected** slope instead (Harrell/Steyerberg).
+
+```python
+import numpy as np, statsmodels.api as sm
+X = ...            # design matrix (add_constant), y = 0/1 outcome
+def cal_slope(y, lp):
+    m = sm.GLM(y, sm.add_constant(lp), family=sm.families.Binomial()).fit()
+    return m.params[1], m.params[0]          # slope, calibration-in-the-large intercept
+
+full = sm.GLM(y, X, family=sm.families.Binomial()).fit()
+app_slope, app_int = cal_slope(y, X @ full.params)     # apparent: slope ~1.00, intercept ~0
+
+rng = np.random.default_rng(42); n = len(y); opt = []
+for _ in range(500):                                    # bootstrap optimism (Harrell)
+    idx = rng.integers(0, n, n)
+    bm = sm.GLM(y[idx], X[idx], family=sm.families.Binomial()).fit()
+    s_boot, _ = cal_slope(y[idx], X[idx] @ bm.params)   # boot model on boot data (apparent)
+    s_orig, _ = cal_slope(y,      X      @ bm.params)   # boot model on original data (test)
+    opt.append(s_boot - s_orig)
+corrected_slope = app_slope - float(np.mean(opt))       # < 1.00 when the model overfits
+print(f"apparent slope {app_slope:.3f} -> optimism-corrected {corrected_slope:.3f}")
+```
+
+A corrected slope **< 1** means predictions are too extreme (overfit) and should be shrunk
+(a penalized/uniform-shrinkage refit); a slope **> 1** means they are too moderate.
+
+---
+
+## The four levels of calibration (report weak calibration at least)
+
+Van Calster's hierarchy — report at minimum **weak calibration** (intercept + slope):
+
+- **Mean** (calibration-in-the-large): mean predicted = observed event rate (the intercept).
+- **Weak**: intercept ≈ 0 **and** slope ≈ 1.
+- **Moderate**: a **flexible calibration curve** (loess / spline of observed on predicted),
+  not decile bins — the plot most reviewers now expect.
+- **Strong**: correct per-covariate (rarely achievable; not required).
+
+```python
+import matplotlib.pyplot as plt
+from sklearn.calibration import calibration_curve
+phat = full.predict(X)
+frac_pos, mean_pred = calibration_curve(y, phat, n_bins=10, strategy="quantile")
+plt.plot([0, 1], [0, 1], "--"); plt.plot(mean_pred, frac_pos, "o-")   # add a loess curve for moderate
+plt.xlabel("Predicted probability"); plt.ylabel("Observed frequency")
+```
+
+---
+
+## Brier score; do NOT rely on Hosmer–Lemeshow
+
+- **Brier score** = mean squared error of the probabilities; report the **scaled Brier**
+  (1 − Brier / Brier_null) so it is interpretable against the event rate.
+- **Hosmer–Lemeshow is deprecated** (Van Calster 2016; Austin & Steyerberg): its p-value depends
+  on an arbitrary number of bins, it is underpowered in small samples and rejects trivially in
+  large ones, and it gives no direction or magnitude. Report the **calibration slope + intercept
+  + a flexible calibration plot** instead of an H–L p-value.
+
+```python
+from sklearn.metrics import brier_score_loss
+brier = brier_score_loss(y, phat); scaled = 1 - brier / (y.mean() * (1 - y.mean()))
+```
+
+## Survival models
+
+For a Cox/survival model, calibrate the **predicted vs observed risk at a fixed horizon**
+(e.g. 3-year): group by predicted-risk decile and compare to a Kaplan–Meier / pseudo-value
+estimate at that time, or use `rms::calibrate` / `pec` in R with bootstrap optimism correction.
+State the horizon; a model can be well-calibrated at 1 year and not at 5.
+
+---
+
+## Reporting
+
+- Calibration **intercept and slope** with the **internal-validation method named**
+  (bootstrap/CV), not the apparent slope of 1.00; the flexible calibration plot.
+- Scaled Brier; the horizon (survival); the cohort each metric was computed on (development vs
+  held-out vs external) stated explicitly.
+- Discrimination **and** calibration together; add decision-curve net benefit for a utility claim
+  (see `table-standards/table-types/incremental_value.md` and the `make-figures` decision-curve
+  exemplar).
+
+---
+
+## Common failures (flag at review)
+
+- **Apparent calibration slope of exactly 1.00** (and intercept 0) with no bootstrap/CV/external
+  token — in-sample fit presented as calibration (S7).
+- **Hosmer–Lemeshow p-value** offered as the calibration evidence (deprecated).
+- **Discrimination reported without calibration** for a model meant to guide care (S7 → MAJOR).
+- **Decile-bin calibration only**, no flexible curve; or a survival calibration with no stated
+  horizon.
+
+---
+
+## Anti-Hallucination
+
+- Never hand-type a calibration slope/intercept, Brier, or CI — compute it from predictions with
+  a seeded script.
+- Do not report a calibration slope of 1.00 as evidence of good calibration — it is the
+  apparent-fit artifact; report the optimism-corrected value the bootstrap produced.
+- Name the validation source of every calibration number (development / bootstrap-corrected /
+  external); do not present development-sample calibration as validated performance.