medsci-skills 5.16.0 → 5.17.0

package/README.md

@@ -2,14 +2,14 @@
 
 # MedSci Skills
 
-**54 skills that actually work.** Built by a physician-researcher, tested on real publications.
+**55 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-54-brightgreen?style=flat-square)
+![Skills](https://img.shields.io/badge/Skills-55-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.17** — model-engineering produce-side depth, **completion**. Deployment safety + the final roadmap/candidate items: a new **`uncertainty-imaging`** skill + `check_uncertainty_reporting` gate (calibrated per-case uncertainty / OOD guard on a held-out set / abstention at a pre-specified target / calibration-under-shift — for a deployment-framed model), an **MLOps wiring reference** for `model-scaffold` (experiment tracking, config/data/environment versioning, CI-for-ML — pointing to W&B / MLflow / nnU-Net, reimplementing nothing), and an **`architecture-zoo` graph-neural-net family card** (GCN / GraphSAGE / GAT / GIN / BrainGNN for brain connectomes) that closes the last candidate gap. The six-item produce-side depth roadmap and its candidate list are now complete. Additive and backward-compatible; **55 skills / 44 guidelines / 50 integrity detectors / 22 domain-probe modules**. (See the [CHANGELOG](CHANGELOG.md) for v5.0–v5.16.)
+
 **v5.16** — model-engineering produce-side depth, clinical fine-tuning focus (Items 3–4 of the [produce-side depth roadmap](docs/roadmap_model_engineering_depth.md)). A new **`radiomics-ml`** skill + `check_radiomics_ml` gate for the most common solo-doable clinical-ML workflow — radiomics / tabular features → any classical learner (LASSO / SVM / random forest / XGBoost / …) → a clinical outcome, no GPU — with a learner-agnostic nested-CV / calibration / stability gate; plus a **`model-scaffold` fine-tuning mode** (`--task finetune` + `--from-pretrained`) that adapts a pretrained backbone on collected clinical data with a frozen→unfrozen schedule, discriminative learning rates, and a pretrained-weight provenance record (`PRETRAINED.md` + a `PRETRAINED_PROVENANCE_MISSING` verdict on the existing `check_training_hygiene`, plus a MedSAM-adaptation + train-only diffusion-augmentation guide). Additive and backward-compatible; **54 skills / 44 guidelines / 49 integrity detectors / 22 domain-probe modules**. (See the [CHANGELOG](CHANGELOG.md) for v5.0–v5.15.)
 
 **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.)
@@ -455,14 +457,14 @@ ma-scout -> search-lit -> fulltext-retrieval -> design-study ──> write-proto
 
 ### By research stage
 
-All 54 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/).
+All 55 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` · `radiomics-ml` · `model-card` · `mllm-eval` |
+| 🤖 **Medical-AI model engineering** | `preprocess-imaging` · `architecture-zoo` · `model-scaffold` · `model-validation` · `model-evaluation` · `uncertainty-imaging` · `explainability` · `radiomics-ml` · `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` |
@@ -491,6 +493,7 @@ All 54 skills, grouped by where they fit in the clinical-manuscript and medical-
 | **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. |
 | **radiomics-ml** | Produce or audit a radiomics / tabular clinical-ML study — features → random forest / XGBoost / regularised logistic → clinical outcome — the most common solo-doable clinical-ML workflow (no GPU, no engineer). Emits a pipeline manifest + a deterministic rigor gate (`check_radiomics_ml`): `NO_NESTED_CV`, `HIGH_DIM_LOW_EVENTS`, `SELECTION_OUTSIDE_CV` (Major); `NO_FEATURE_STABILITY`, `NO_CALIBRATION`, `NO_EXTERNAL_VALIDATION` (Minor). pyradiomics/IBSI settings, nested CV with in-fold selection, ICC stability, SHAP, calibration + decision curve, CLEAR/TRIPOD+AI/PROBAST-AI reporting. Integrates scikit-learn / xgboost / pyradiomics; never reimplements them. |
+| **uncertainty-imaging** | Design or audit the uncertainty / out-of-distribution / selective-prediction layer of a deployment-framed medical-imaging model — so a clinical-use claim carries calibrated per-case uncertainty (MC-dropout / deep ensemble / conformal / Bayesian), an OOD guard validated on a held-out OOD set, an abstention rule at a pre-specified operating point, and calibration checked under distribution shift. Emits an uncertainty manifest + a deterministic gate (`check_uncertainty_reporting`): `POINT_PREDICTION_NO_UNCERTAINTY`, `CONFORMAL_NO_COVERAGE_VALIDATION`, `OOD_NO_HELDOUT_SET` (Major); `ENSEMBLE_NOT_INDEPENDENT`, `MCDROPOUT_DISABLED_AT_INFERENCE`, `SELECTIVE_NO_TARGET`, `NO_CALIBRATION_UNDER_SHIFT` (Minor). Integrates MAPIE / captum / OOD scorers; 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. |

package/metadata/distribution_files.json

@@ -423,8 +423,8 @@
     },
     {
       "path": "skills/architecture-zoo/SKILL.md",
-      "size": 5712,
-      "sha256": "ffb9a52d417f309a3b22c8d0f74e6700b67350c0d7a2a2e2c785f0cb4cb066bc"
+      "size": 6094,
+      "sha256": "abb4656f36e0ef068508269ce2ec87c832b7c8fb13c4cbc44af27b2dc8058bff"
     },
     {
       "path": "skills/architecture-zoo/references/classification.md",
@@ -441,10 +441,15 @@
       "size": 5267,
       "sha256": "495453b025f1cb13d5ba0bac9be6d3b0d63dd958ea48d2b9e55bc222e9c26786"
     },
+    {
+      "path": "skills/architecture-zoo/references/graph.md",
+      "size": 6913,
+      "sha256": "d6bea2d61a2f1d515810d1bf96bef80f156d816998134a3c911e6c4585728c2e"
+    },
     {
       "path": "skills/architecture-zoo/references/index.md",
-      "size": 4024,
-      "sha256": "d2360eb8635347f0f22be0b0e337a540db865aafdc12678455cf32bc49fd9d3d"
+      "size": 4334,
+      "sha256": "f812ec9afe2ba06c42da8de851cea08632d61eb98e87cd3edd7cdd17f39e226e"
     },
     {
       "path": "skills/architecture-zoo/references/segmentation.md",
@@ -458,8 +463,8 @@
     },
     {
       "path": "skills/architecture-zoo/skill.yml",
-      "size": 2836,
-      "sha256": "7d7c727a9fc75383e775feac14faf1c4caad90307ed8ca20859ef499ac17deb0"
+      "size": 2851,
+      "sha256": "c9e03a47973bab737587d22ebac4cd7b27b5c5af55a271efb8f71abba7fa70cf"
     },
     {
       "path": "skills/author-strategy/SKILL.md",
@@ -2868,18 +2873,23 @@
     },
     {
       "path": "skills/model-scaffold/SKILL.md",
-      "size": 9237,
-      "sha256": "d7e736178cb60d2d13cef9174474297bd54bc6d4d1f3862023d802ff0c034a95"
+      "size": 9527,
+      "sha256": "8fcf4060f064a1924d4bec278e0c0c628c99caf6ea75f617f8b9748cbb207ed8"
     },
     {
       "path": "skills/model-scaffold/references/finetuning_guide.md",
       "size": 6208,
       "sha256": "b7817d53eeeb506b573beaae1889fa863dd81286d474ab99b46b38ad046b32e7"
     },
+    {
+      "path": "skills/model-scaffold/references/mlops_guide.md",
+      "size": 5171,
+      "sha256": "cc9b62ed588daf97b40b6d7a8e27f9b6de96b9f5752ad2baa8e180e01d3d4973"
+    },
     {
       "path": "skills/model-scaffold/references/training_guide.md",
-      "size": 2661,
-      "sha256": "4a3197a89b8d3473071051f67a7bcf40f71ecf007e942f81e9c40dc48fce1a9c"
+      "size": 2840,
+      "sha256": "9a7f7b5dda65e71d8007cb6539cda0cfb9c6b1f2c877aedee4646f368686e96f"
     },
     {
       "path": "skills/model-scaffold/scripts/check_training_hygiene.py",
@@ -4031,6 +4041,56 @@
       "size": 1911,
       "sha256": "7f549269905cad97493d7699dad0068e410e8a8d771814988911bec5b0648d4c"
     },
+    {
+      "path": "skills/uncertainty-imaging/SKILL.md",
+      "size": 8224,
+      "sha256": "0ff26311b9b372a074751d9b64c5fc20ec7440aabe76fd17c3f2e09d54d4a080"
+    },
+    {
+      "path": "skills/uncertainty-imaging/references/uncertainty_guide.md",
+      "size": 5574,
+      "sha256": "fb63c7b48b00fc371dca2ed1a7bdb9932b318ceba6334bae5097f4da3b08b38a"
+    },
+    {
+      "path": "skills/uncertainty-imaging/scripts/check_uncertainty_reporting.py",
+      "size": 13042,
+      "sha256": "2f14f78da71254d82977c8edc9f8c32bcde2e6d6d8e9c971af8114219ce558b5"
+    },
+    {
+      "path": "skills/uncertainty-imaging/scripts/check_uncertainty_reporting_challenge/expected/strong.txt",
+      "size": 414,
+      "sha256": "2d3f1cbeb88b00d1ef8968c276f17d276c152eafbf445d3879315bd727a16c61"
+    },
+    {
+      "path": "skills/uncertainty-imaging/scripts/check_uncertainty_reporting_challenge/expected/weak.txt",
+      "size": 1077,
+      "sha256": "b37379da88b17881678d50534ad993823a9a7c3b96a9942ca45be21caed39aaf"
+    },
+    {
+      "path": "skills/uncertainty-imaging/scripts/check_uncertainty_reporting_challenge/fixture/uncertainty_strong.json",
+      "size": 323,
+      "sha256": "39a64a9e327bf00151d3bb7e1394e7ba87c04ed0df6523256f22d55c127320bf"
+    },
+    {
+      "path": "skills/uncertainty-imaging/scripts/check_uncertainty_reporting_challenge/fixture/uncertainty_weak.json",
+      "size": 204,
+      "sha256": "5748d22600c8f68485f3ab665c32eace4a4dfc827df7f98c1c09640d82f304c2"
+    },
+    {
+      "path": "skills/uncertainty-imaging/scripts/check_uncertainty_reporting_challenge/problem.md",
+      "size": 2460,
+      "sha256": "fb3350f915b3b4a36a91718f93837f4331410d209f66fbd7e7d751fd35af4cc9"
+    },
+    {
+      "path": "skills/uncertainty-imaging/scripts/check_uncertainty_reporting_challenge/verify.sh",
+      "size": 2117,
+      "sha256": "5ff542ed3c4b0a479a6c2f906cefbb75494cb1ca8118e121afaf45f07f31bb80"
+    },
+    {
+      "path": "skills/uncertainty-imaging/skill.yml",
+      "size": 3753,
+      "sha256": "a229c56e3133db1ed616880f76903bbf825ee59591eb26534d4ddb172cf0945c"
+    },
     {
       "path": "skills/verify-refs/SKILL.md",
       "size": 11846,

package/metadata/distribution_manifest.json

@@ -1,6 +1,6 @@
 {
   "schema_version": 1,
-  "version": "5.16.0",
+  "version": "5.17.0",
   "owned_skills": [
     "academic-aio",
     "add-journal",
@@ -52,6 +52,7 @@
     "self-review",
     "setup-medsci",
     "sync-submission",
+    "uncertainty-imaging",
     "verify-refs",
     "version-dataset",
     "write-paper",

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": 54,
+  "skill_count": 55,
   "categories": [
     {
       "key": "literature_references",
@@ -39,7 +39,8 @@
         "model-scaffold",
         "model-validation",
         "preprocess-imaging",
-        "radiomics-ml"
+        "radiomics-ml",
+        "uncertainty-imaging"
       ]
     },
     {
@@ -562,6 +563,15 @@
       "maturity": "official",
       "description": "Audit SSOT-to-submission drift and create journal submission manifests from canonical manuscript artifacts."
     },
+    {
+      "slug": "uncertainty-imaging",
+      "category": "model_engineering",
+      "category_label": "Model Engineering & Validation",
+      "layer": "D",
+      "owner_domain": "model_validation",
+      "maturity": "official",
+      "description": "Design or audit the uncertainty-quantification, out-of-distribution (OOD) detection, and selective-prediction layer of a medical-imaging model framed for deployment — so a clinical-use claim carries c…"
+    },
     {
       "slug": "verify-refs",
       "category": "literature_references",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "medsci-skills",
-  "version": "5.16.0",
+  "version": "5.17.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/architecture-zoo/SKILL.md

@@ -7,9 +7,10 @@ description: >
   when-to-use, a medical-imaging use, a reference implementation, the typical validation setup, and the
   matching model-scaffold template. Covers 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). It teaches archetypes and the task-to-architecture
-  logic, not a live SOTA leaderboard.
-triggers: architecture zoo, which architecture, choose a model, model selection, ResNet vs ViT, U-Net vs nnU-Net, what backbone, foundation model for, transfer learning choice, MedSAM, TotalSegmentator, DINO, MAE, self-supervised, paper to architecture, reference implementation, when to use ViT, segmentation architecture, classification backbone
+  TotalSegmentator, BiomedCLIP, DINO/MAE/SimCLR; and graph neural nets — GCN/GraphSAGE/GAT/GIN/BrainGNN —
+  for brain connectomes). It teaches archetypes and the task-to-architecture logic, not a live SOTA
+  leaderboard.
+triggers: architecture zoo, which architecture, choose a model, model selection, ResNet vs ViT, U-Net vs nnU-Net, what backbone, foundation model for, transfer learning choice, MedSAM, TotalSegmentator, DINO, MAE, self-supervised, graph neural network, GNN, brain connectome, GCN, GAT, GraphSAGE, BrainGNN, population graph, paper to architecture, reference implementation, when to use ViT, segmentation architecture, classification backbone
 tools: Read, Write, Edit, Grep, Glob
 model: inherit
 ---
@@ -62,6 +63,8 @@ a family card.
   VAE / fastMRI reconstruction.
 - `${CLAUDE_SKILL_DIR}/references/foundation_models.md` — SAM / MedSAM / MedSAM2 / TotalSegmentator /
   SegVol / BiomedCLIP / DINO / MAE / SimCLR / MoCo.
+- `${CLAUDE_SKILL_DIR}/references/graph.md` — GCN / GraphSAGE / GAT / GIN / BrainGNN for brain
+  connectomes & population graphs (integrate PyTorch Geometric / DGL; not scaffolded by model-scaffold).
 Each card gives the paper, core idea, when-to-use, medical-imaging use, reference implementation, and the
 **typical validation/experiment setup** for that architecture class.
 

package/skills/architecture-zoo/references/graph.md

@@ -0,0 +1,110 @@
+# Graph neural networks — brain connectomes & population graphs (architecture-zoo)
+
+For when the data is a **graph, not an image grid**: a brain **connectome** (nodes = ROIs /
+parcels, edges = structural connectivity from DTI tractography or functional connectivity
+from fMRI correlation), or a **population graph** (nodes = subjects, edges = phenotypic /
+imaging similarity). The task is usually **graph-level classification** (diagnose a subject
+from their connectome), **node-level** (flag abnormal ROIs, or classify subjects on a
+population graph), or **link prediction** (connectivity changes).
+
+This is a distinct family because a CNN/U-Net assumes a regular pixel grid; a connectome has
+no grid — permuting the ROI order must not change the prediction, which is exactly the
+symmetry a GNN respects. Each card: **paper → core idea → when to use → medical use →
+reference impl → validation/experiment setup.**
+
+---
+
+## The general-purpose message-passing GNNs
+
+### GCN (graph convolutional network)
+- **Paper**: Kipf & Welling, "Semi-Supervised Classification with Graph Convolutional
+  Networks", *ICLR* 2017.
+- **Core idea**: each layer averages a node's features with its neighbours' (a first-order
+  spectral-graph approximation), stacking to widen the receptive field over the graph.
+- **When to use**: the transparent baseline for any connectome / population-graph task — try
+  it before anything fancier.
+- **Medical use**: connectome classification; **Parisot et al.** (*Medical Image Analysis*
+  2018) put subjects on a **population graph** (phenotypic-similarity edges) for autism
+  (ABIDE) and Alzheimer's (ADNI) prediction — a semi-supervised node-classification framing.
+- **Reference impl**: **PyTorch Geometric** (`GCNConv`) or **DGL**; do not reimplement.
+- **Validation setup**: split at the **subject level** (a subject's graph — or, on a
+  population graph, a subject node's label — never spans train/test); with a small cohort,
+  report a **permutation test** and cross-validated CIs, not a single split.
+
+### GraphSAGE (inductive aggregation)
+- **Paper**: Hamilton, Ying & Leskovec, "Inductive Representation Learning on Large Graphs",
+  *NeurIPS* 2017.
+- **Core idea**: learn an **aggregator** over a sampled neighbourhood so the model generalises
+  to **unseen** nodes/graphs (inductive), unlike transductive GCN.
+- **When to use**: a **new subject** must be classified without retraining (the realistic
+  clinical setting), or the graph is too large to process whole.
+- **Medical use**: inductive connectome classification where test subjects are genuinely held
+  out (the honest deployment framing for a population-graph model).
+- **Reference impl**: PyTorch Geometric (`SAGEConv`) / DGL.
+- **Validation setup**: exploit the inductive setup to keep the test subjects fully out of
+  message passing during training (transductive leakage is a real trap on population graphs).
+
+### GAT (graph attention)
+- **Paper**: Veličković et al., "Graph Attention Networks", *ICLR* 2018.
+- **Core idea**: learn **attention weights** over neighbours, so the model decides which
+  connections matter instead of averaging uniformly.
+- **When to use**: when *which edges/connections drive the prediction* is itself a finding
+  (edge importance is a built-in interpretability signal).
+- **Medical use**: connectome studies that report the most-attended edges/ROIs as candidate
+  biomarkers.
+- **Reference impl**: PyTorch Geometric (`GATConv` / `GATv2Conv`) / DGL.
+- **Validation setup**: treat attention as a **hypothesis-generating** attribution, not proof
+  — sanity-check it (does it survive label permutation?) as `/explainability` requires of any
+  saliency.
+
+### GIN (graph isomorphism network)
+- **Paper**: Xu et al., "How Powerful are Graph Neural Networks?", *ICLR* 2019.
+- **Core idea**: an aggregation as discriminative as the Weisfeiler-Lehman test — the most
+  **expressive** simple GNN for **graph-level** classification.
+- **When to use**: graph-level diagnosis where subtle topology differences separate classes
+  and GCN/GAT underfit.
+- **Reference impl**: PyTorch Geometric (`GINConv`).
+- **Validation setup**: expressiveness raises overfitting risk on small connectome cohorts —
+  pair with heavy regularisation and nested CV (as `/radiomics-ml` does for the p ≫ n regime).
+
+---
+
+## The brain-specific model
+
+### BrainGNN (ROI-aware, interpretable)
+- **Paper**: Li et al., "BrainGNN: Interpretable Brain Graph Neural Network for fMRI Analysis",
+  *Medical Image Analysis* 2021.
+- **Core idea**: ROI-aware convolution + a pooling layer that scores and selects the most
+  informative ROIs, so the model is **interpretable at the region level** by construction.
+- **When to use**: fMRI connectome classification where you must report **which ROIs** drove
+  the decision (the usual neuroimaging reviewer demand).
+- **Medical use**: task-fMRI / resting-state connectome diagnosis (ASD, disorders) with a
+  salient-ROI readout.
+- **Reference impl**: the authors' released BrainGNN repo (on PyTorch Geometric).
+- **Validation setup**: report salient ROIs with **stability across folds** (not one split);
+  keep site-harmonisation (**ComBat**) fit on the **training** fold only.
+
+---
+
+## Connectome-specific validation traps (read before publishing)
+- **Subject-level split.** A subject's connectome must not appear in more than one split; on a
+  population graph, hold test-subject **labels** out of training and (ideally, inductive)
+  their **nodes** out of message passing. This is `/model-validation`'s split-leakage discipline
+  at the subject level.
+- **Site / scanner harmonisation leakage.** Multi-site connectome data (ABIDE, ADNI) is
+  harmonised with **ComBat** — fit it on the **training** fold only, never the whole cohort
+  (the graph analogue of `/preprocess-imaging`'s `NORMALIZATION_LEAKAGE`).
+- **p ≫ n.** A connectome has thousands of edges on tens–hundreds of subjects; treat it like
+  radiomics — nested CV, regularisation, a **permutation test** for tiny cohorts, and don't
+  over-read a single fold (`/radiomics-ml`).
+- **Interpretability ≠ proof.** Attention / ROI-saliency is hypothesis-generating; sanity-check
+  it (`/explainability`).
+
+## Boundary — this family is not scaffolded by `/model-scaffold`
+`/model-scaffold` builds **image-grid** repos (CNN / U-Net / transformer); it has **no graph
+task template**. For GNNs, **integrate PyTorch Geometric / DGL directly** — they own the graph
+layers, loaders, and training loop; the lane does not reimplement them. The lane's
+**subject-level** gates still apply: `/model-validation` (split leakage), `/radiomics-ml`
+(nested-CV rigor for p ≫ n), `/explainability` (attribution sanity), `/uncertainty-imaging`
+(deployment uncertainty), and `/check-reporting` (TRIPOD+AI). Record the choice + paper in the
+decision note; validate the built model with `/model-validation`.

package/skills/architecture-zoo/references/index.md

@@ -14,12 +14,16 @@ per-paper detail and the `/model-scaffold` template to instantiate.
 | "I have few labels / want to pretrain on unlabelled scans" | **self-supervised pretraining → fine-tune** | `foundation_models.md` |
 | "adapt a released medical foundation model" | **transfer / prompt a foundation model** | `foundation_models.md` |
 | "synthesise / translate a modality" (MRI→CT, denoise) | **image-to-image / generative** | `synthesis.md` |
+| "classify from a brain connectome / graph" (ROI connectivity, DTI/fMRI) | **graph neural network** | `graph.md` |
 | "generate a report / answer a visual question" | **multimodal LLM** | *(use `/mllm-eval`; not a CNN choice)* |
 
 ## Step 2 — let the constraints narrow it
 - **Modality / dimensionality**: 2-D (CXR, fundus, path tiles, single CT/MR slices) →
   2-D backbones / 2-D U-Net. 3-D volumes (CT, MR) → **3-D U-Net / SegResNet / nnU-Net**
-  (3-D context matters; do not collapse to slices if the structure is volumetric).
+  (3-D context matters; do not collapse to slices if the structure is volumetric). A
+  **graph** (brain connectome, ROI-connectivity matrix — no pixel grid) → a **GNN**
+  (`graph.md`); integrate PyTorch Geometric / DGL directly (`/model-scaffold` has no graph
+  template).
 - **Labelled data scale** (events/structures, not just images):
   - **small** (hundreds) → a **pretrained** backbone fine-tuned (ImageNet / a medical
     foundation model), strong augmentation, heavy regularisation; prefer **nnU-Net**

package/skills/architecture-zoo/skill.yml

@@ -29,7 +29,7 @@ safety_boundaries:
   - "Advisory only: it writes a decision note, never code or weights; the build is /model-scaffold."
   - "Every recommendation names its source paper; benchmark numbers are cited, never invented; the zoo describes archetypes, not a live leaderboard."
 known_limitations:
-  - "The literature moves fast; this is a curated archetype map (classification, segmentation, detection, synthesis, foundation/SSL families), not an exhaustive or current SOTA ranking."
+  - "The literature moves fast; this is a curated archetype map (classification, segmentation, detection, synthesis, foundation/SSL, and graph/GNN families), not an exhaustive or current SOTA ranking."
   - "A sound architecture choice is necessary, not sufficient; validity still depends on the split, validation design, and metrics (/model-validation, /model-evaluation)."
 validation_commands:
   - "carry the decision note into /model-scaffold to instantiate the chosen template, then /model-validation"

package/skills/model-scaffold/SKILL.md

@@ -100,7 +100,10 @@ adaptation and train-only diffusion augmentation). Run `python train.py` (best m
 ### Phase 5 — Validate, evaluate, publish
 Hand off to `/model-validation` (validation-tier + comparator + metric-selection audit),
 `/model-evaluation` + `/analyze-stats` (Dice + HD95/NSD with CIs), `/make-figures`, and `/write-paper`
-(fill the `methods_stub.md` `[VERIFY]` placeholders) + `/check-reporting` (CLAIM 2024 / TRIPOD+AI).
+(fill the `methods_stub.md` `[VERIFY]` placeholders) + `/check-reporting` (CLAIM 2024 / TRIPOD+AI). For
+reproducibility-safe wiring of experiment tracking (W&B / MLflow), config / data / environment
+versioning, and the MLOps reporting checklist, see `${CLAUDE_SKILL_DIR}/references/mlops_guide.md`
+(a wiring + reporting reference — it points to the frameworks, it does not replace them).
 
 ## Runnability — honest contract
 The generated repo is **runnable**, but runnability is **not a CI guarantee**. The default gates prove

package/skills/model-scaffold/references/mlops_guide.md

@@ -0,0 +1,77 @@
+# MLOps wiring guide (model-scaffold)
+
+Load-on-demand notes for taking a scaffolded repo through a **reproducible, reportable**
+training run. This is a **wiring and reporting** reference, **not** a training-loop,
+hyperparameter-search, or experiment-tracking reimplementation. Training and tracking stay
+with the frameworks — MONAI / nnU-Net / timm for the model, Weights & Biases / MLflow /
+TensorBoard for tracking, DVC / git-lfs for data — and this guide covers how to wire them so
+the run is reproducible and what to record so a reviewer can trust it. Everything here points
+to a framework; nothing here replaces one (the [ROADMAP out-of-scope clause](../../../ROADMAP.md)).
+
+## The reproducibility contract (what a run must be able to reproduce)
+A training run is reproducible when, from the recorded artifacts alone, someone else can
+re-derive the same result. That needs five things pinned, all of which the scaffold already
+emits a slot for:
+1. **Code** — the git commit of the repo (dirty trees are not reproducible; commit first).
+2. **Config** — `config.yaml` as the single source of truth (task, arch, channels, split
+   fractions, seed). Do not scatter hyperparameters across the CLI and the code.
+3. **Data** — a content hash of the exact dataset (see `/version-dataset`), not just a path.
+4. **Seed + determinism** — the scaffold's `seed_everything` seeds Python / NumPy / torch /
+   CUDA and sets cuDNN deterministic; record the seed in the tracker and `REPRODUCIBILITY.md`.
+5. **Environment** — a pinned `requirements.txt` (exact versions), CUDA / driver, GPU model.
+
+## Experiment tracking (integrate, don't build one)
+Log to **W&B**, **MLflow**, or **TensorBoard** — pick one, do not write a tracker. At run
+start, log the whole `config.yaml`, the git commit, the dataset hash, and the seed as the run
+config; during training log per-epoch train/val loss + the val metric; at the end log the best
+checkpoint as an artifact. The tracker's run URL / ID becomes part of the Methods record. Keep
+the scaffold's contract intact — the best model is still selected on the **val** split, the
+**test** split is still touched once by `evaluate.py`.
+
+## Config management
+The emitted `config.yaml` is the SSOT for one run. For sweeps, drive them with **Hydra /
+OmegaConf** (or the tracker's sweep feature) that *reads* this config — never hand-edit values
+into `train.py`. A hyperparameter that isn't in the config isn't reproducible.
+
+## Data & model versioning
+- **Data** — hash the training set with `/version-dataset` and record the manifest hash in the
+  run config, so "trained on dataset X" is verifiable, not asserted. For large data use **DVC**
+  or **git-lfs**; commit the pointer, not the pixels.
+- **Model** — document the trained model with `/model-card` (Model Card + Datasheet); for a
+  fine-tune, the pretrained-weight provenance lives in `PRETRAINED.md`
+  (see `references/finetuning_guide.md`).
+
+## Environment capture
+Pin `requirements.txt` to exact versions before publishing (`pip freeze`, or a `conda env
+export`). For a hard reproducibility guarantee, a Dockerfile / container digest removes "works
+on my machine". Record the CUDA / driver / GPU — some GPU ops are non-deterministic even with
+cuDNN deterministic set, which is why metrics are reported as **mean ± SD over ≥ 3 seeds**, not
+a single run.
+
+## Pipeline orchestration — use the framework's, not a new one
+For segmentation, **nnU-Net** owns preprocessing → training → inference as a pipeline; build
+its `dataset.json` folds from the scaffold's `splits/split_assignment.csv` so the patient-level
+split is preserved end to end. **MONAI bundles** package a model + transforms + metadata the
+same way. Orchestrate with the framework's own pipeline; do not rebuild one.
+
+## CI for an ML repo (what is worth gating)
+CI should gate the **network-free, deterministic** properties — not full training. The scaffold
+already ships these: `check_training_hygiene` (seeds, eval-mode inference, train-only loaders,
+pretrained provenance) and the split-leakage proof (`/model-validation`). Add a **forward-pass
+smoke** (build the model, one batch, check output shape) as a fast job. Do **not** put a real
+training run in CI — it is slow, non-deterministic, and not what CI is for.
+
+## What to report (the MLOps reporting checklist)
+State, in Methods or a reproducibility appendix: the **compute environment** (framework +
+versions, CUDA / driver, GPU), the **seed(s)** and that metrics are mean ± SD over ≥ 3 seeds,
+the **config** (as a supplement or a tracker link), the **dataset version** (`/version-dataset`
+hash), and the **tracking run** URL / ID. This is the reproducibility half of TRIPOD+AI /
+CLAIM 2024; `/check-reporting` covers the items.
+
+## Hand-offs
+- Dataset hash / reproducibility-lock → `/version-dataset`.
+- Model + dataset documentation → `/model-card`.
+- Split / validation-design audit → `/model-validation`.
+- Held-out metrics + CIs → `/model-evaluation` → `/analyze-stats`.
+- Deployment uncertainty / OOD / monitoring → `/uncertainty-imaging`.
+- Reporting fit → `/check-reporting` (TRIPOD+AI / CLAIM / DECIDE-AI).

package/skills/model-scaffold/references/training_guide.md

@@ -34,7 +34,9 @@ with cuDNN deterministic set).
 Before publishing, complete `REPRODUCIBILITY.md`: pinned `requirements.txt`
 (torch/monai/... exact versions), CUDA/driver, GPU model, the git commit of the repo,
 and the seed. Pair with `/version-dataset` to hash the exact dataset the model trained
-on.
+on. For reproducibility-safe wiring of experiment tracking (W&B / MLflow), config / data
+/ environment versioning, CI-for-ML, and the MLOps reporting checklist, see
+`mlops_guide.md`.
 
 ## Hand-offs
 - Split / validation-design audit → `/model-validation` (run `check_split_leakage.py`