medsci-skills 5.14.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

@@ -1081,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,
@@ -3181,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,
@@ -3758,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",

package/metadata/distribution_manifest.json

@@ -1,6 +1,6 @@
 {
   "schema_version": 1,
-  "version": "5.14.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.14.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/explainability/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: explainability
+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 reviewer expects: 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 rather than cherry-picked cases, and attribution framing rather than
+  "proof the model is correct". Emits an explainability-report manifest and a deterministic rigor gate.
+  Integrates captum / pytorch-grad-cam; it does not reimplement them, and never runs a model on real
+  patient data.
+triggers: explainability, interpretability, saliency, saliency map, grad-cam, gradcam, grad-cam++, attention map, attention rollout, integrated gradients, captum, pytorch-grad-cam, heatmap, class activation map, CAM, feature attribution, sanity check, Adebayo, model randomization, localization metric, pointing game, IoU with ground truth, XAI, explainable AI, model looks at, faithfulness
+tools: Read, Write, Edit, Bash, Grep, Glob
+model: inherit
+---
+
+# Explainability Skill
+
+## Purpose
+
+A saliency / Grad-CAM heat-map is the **most over-interpreted artifact** in medical-imaging AI: a
+colourful map over the lesion is routinely presented as proof the model "looks at the right thing."
+Adebayo et al. (*NeurIPS* 2018) showed many saliency methods produce visually convincing maps that are
+**independent of the model's learned weights and of the labels** — so they explain nothing. This skill
+produces an explainability analysis that clears the rigor bar, and audits an existing one, so the map
+is trustworthy before it reaches a manuscript (CLAIM 2024 / TRIPOD+AI interpretability items).
+
+It sits alongside evaluation in the lane: `/architecture-zoo` → `/preprocess-imaging` →
+`/model-scaffold` → `/model-validation` → `/model-evaluation` + **explainability** →
+`/write-paper` + `/check-reporting`. It **integrates** captum / pytorch-grad-cam (referenced in the
+plan); it does not reimplement them and never runs a model on real patient data.
+
+## When to use
+- You produced (or are about to produce) saliency / Grad-CAM / attention maps and want them reported
+  to the standard a reviewer expects.
+- You want to audit an explainability analysis for the four failure modes below.
+
+## When NOT to use
+- Discrimination / calibration metrics → `/model-evaluation` then `/analyze-stats`.
+- Split or preprocessing leakage → `/model-validation` / `/preprocess-imaging`.
+- LLM/MLLM faithfulness & hallucination → `/mllm-eval`.
+- Reimplementing captum / pytorch-grad-cam → out of scope (this skill wires and audits them).
+
+## The four failure modes (what the gate enforces)
+1. **Saliency as validation.** A map is *attribution*, not proof the model is correct or that the
+   relationship is causal. Frame it as "where signal is attributed", never as "the model is right".
+2. **No sanity check.** Run the Adebayo **model-randomisation** and **data-randomisation** tests. A map
+   that survives neither is uninterpretable; both axes are the minimum bar.
+3. **No quantitative localisation.** If you claim the map localises the finding, measure it — IoU /
+   pointing game / Dice against ground-truth masks — do not eyeball a few examples.
+4. **Cherry-picked examples.** Report a cohort-level result, not a handful of hand-picked cases.
+
+## Workflow
+
+### Phase 1 — Produce the maps (integrate, don't reimplement)
+Choose the method for the architecture (`references/explainability_guide.md`): Grad-CAM / Grad-CAM++
+for CNNs, attention-rollout for ViTs, integrated-gradients / SHAP for attribution. Wire captum or
+pytorch-grad-cam; do not write a new CAM implementation.
+
+### Phase 2 — Sanity-check and quantify
+- Run the **model-parameter randomisation** and **data (label) randomisation** tests (Adebayo 2018);
+  a faithful map degrades when the model/labels are randomised.
+- Compute a **quantitative localisation metric** against ground-truth masks (IoU / pointing game /
+  Dice) over the cohort — not a visual impression.
+
+### Phase 3 — Emit the explainability-report manifest
+```json
+{
+  "method": "grad-cam++",
+  "n_examples": 200,
+  "cohort_level": true,
+  "localization_metric": "iou",
+  "localization_value": 0.63,
+  "sanity_checks": ["model_randomization", "data_randomization"],
+  "interpretation": "localization"
+}
+```
+`interpretation`: `attribution` / `localization` / `faithfulness` (descriptive) — never
+`validation` / `causal` (overclaim).
+
+### Phase 4 — Gate the report (deterministic)
+```bash
+python3 scripts/check_explainability_report.py --manifest explainability_report.json --strict
+```
+Verdicts: `SALIENCY_AS_VALIDATION`, `NO_SANITY_CHECK`, `NO_LOCALIZATION_METRIC` (Major);
+`INSUFFICIENT_SANITY`, `CHERRY_PICKED_EXAMPLES`, `MISSING_METHOD` (Minor). The verdict is reproduced
+by rule on the manifest, never asserted from prose.
+
+## Integration
+- **`/model-evaluation`** — explainability accompanies the held-out metrics as a secondary analysis.
+- **`/self-review`** `ai_overclaiming` / `image_synthesis` probes audit saliency overclaiming in a
+  finished manuscript; this skill *produces* the rigorous analysis they look for.
+- **`/check-reporting`** — the manifest documents the CLAIM 2024 / TRIPOD+AI interpretability items.
+
+## Anti-Hallucination
+
+- **Never fabricate saliency maps, localisation metrics, or sanity-check results.** Every value in the
+  manifest comes from the researcher's executed XAI code — never invented. This skill designs and
+  audits the analysis; it does not run a model on real patient data.
+- **Never present a saliency map as proof of model correctness or causation.** A map is attribution;
+  claiming it validates the model is the overclaim this skill exists to prevent (`SALIENCY_AS_VALIDATION`).
+- **Never report an explainability-audit "pass" without running `check_explainability_report.py`.** The
+  rigor verdict is reproduced deterministically, never asserted from prose.
+- **Integrate, don't reimplement.** Reference captum / pytorch-grad-cam; do not write a new CAM /
+  attribution implementation or claim results for one.
+
+## Reproducible challenge
+`scripts/check_explainability_report_challenge/` ships a synthetic weak/strong report pair with a
+network-free `verify.sh` wired into the skill's validation commands.

package/skills/explainability/references/explainability_guide.md

@@ -0,0 +1,66 @@
+# Medical-imaging explainability — method, sanity, localisation
+
+Companion to `explainability`. This is *produce* knowledge: which XAI method fits which architecture,
+the sanity checks a faithful map must pass, how to measure localisation quantitatively, and how to
+frame the result honestly. It wires captum / pytorch-grad-cam by name; it does not reimplement them.
+
+## 1. Method by architecture
+
+| Model | Method | Library | Note |
+|---|---|---|---|
+| CNN (ResNet/DenseNet/EfficientNet) | **Grad-CAM / Grad-CAM++** | `pytorch-grad-cam`, `captum` (`LayerGradCam`) | Target the last conv block; Grad-CAM++ handles multiple instances |
+| CNN, fine attribution | **Integrated Gradients**, **SHAP** | `captum` (`IntegratedGradients`), `shap` | Needs a baseline (black/blurred image, not zeros for CT) |
+| Vision Transformer (ViT/Swin) | **Attention rollout**, **Grad-CAM on tokens** | `captum`, custom rollout | Raw attention ≠ explanation; rollout aggregates across layers |
+| Segmentation (U-Net) | Region-level attribution; per-class Grad-CAM | `captum` `LayerGradCam` on the decoder | The mask *is* the localisation; explain the classification head if any |
+| Any | **Occlusion / perturbation** | `captum` (`Occlusion`) | Model-agnostic sanity cross-check for a gradient method |
+
+Pick one primary method and, where feasible, a second of a different family (gradient vs perturbation)
+as a cross-check — agreement between families is stronger evidence than one pretty map.
+
+## 2. Sanity checks (mandatory — Adebayo et al. 2018)
+
+A saliency method can produce a convincing map that is **independent of the model and the labels**.
+Before trusting any map, run both:
+
+- **Model-parameter randomisation test** — progressively randomise the trained weights (top layer →
+  all layers). A *faithful* map degrades toward noise; a map that is unchanged is an edge detector, not
+  an explanation.
+- **Data (label) randomisation test** — retrain on permuted labels. A faithful method's maps should
+  differ from the correctly-trained model's; if identical, the map reflects the input, not the learned
+  function.
+
+Report the outcome (e.g. rank correlation of the map before/after randomisation). Declaring
+`sanity_checks: ["model_randomization", "data_randomization"]` in the manifest is the gate's minimum;
+one axis alone raises `INSUFFICIENT_SANITY`.
+
+## 3. Quantitative localisation (don't eyeball)
+
+If you claim the map "focuses on the lesion", measure it against ground-truth masks/boxes over the
+cohort — not a few examples:
+
+| Metric | What it measures | Range |
+|---|---|---|
+| **IoU / Dice** (thresholded map vs GT mask) | Overlap of the salient region with the finding | 0–1 |
+| **Pointing game** | Does the map's peak fall inside the GT box? (hit rate over cohort) | 0–1 |
+| **Energy-based pointing game** | Fraction of map energy inside the GT mask | 0–1 |
+
+Report the metric **with a denominator** (n cases) and, ideally, a CI. A single annotated example is an
+illustration, not evidence — the gate raises `CHERRY_PICKED_EXAMPLES` when `cohort_level` is not set.
+
+## 4. Framing (attribution, not validation)
+
+- **Say:** "Grad-CAM attributed the prediction to the perihilar region in X% of true positives (IoU
+  0.6)." → `interpretation: localization` / `attribution`.
+- **Do not say:** "The saliency map confirms the model is correct / uses clinically valid features /
+  proves causation." A map shows *where signal is attributed under this method*, not that the decision
+  is right or that the feature is causal. This framing raises `SALIENCY_AS_VALIDATION` (Major).
+- A map that localises well can still accompany a wrong prediction, and a correct prediction can have a
+  diffuse map — localisation and correctness are separate axes.
+
+## 5. Common reviewer objections this pre-empts
+
+1. "Did you sanity-check the saliency method?" → §2, both axes.
+2. "Is the localisation quantified or just shown on one case?" → §3, cohort metric.
+3. "You claim the map validates the model — it doesn't." → §4, reframe as attribution.
+4. "Which layer / baseline / method version?" → declare `method` (and layer/baseline in notes);
+   missing method raises `MISSING_METHOD`.