medsci-skills 5.12.0 → 5.14.0

package/metadata/distribution_files.json

@@ -153,14 +153,24 @@
     },
     {
       "path": "skills/analyze-stats/SKILL.md",
-      "size": 55642,
-      "sha256": "5c4a966490cfb8da6e09ebda897599479bd527d7ee3957ccbfceb5abff06306a"
+      "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,
+      "sha256": "e788d612aa4227500e997ec405ab15a300d28c3b6fb2a1e1df33823764cb9537"
+    },
     {
       "path": "skills/analyze-stats/references/analysis_guides/health_economic_evaluation.md",
       "size": 5362,
@@ -221,6 +231,11 @@
       "size": 12803,
       "sha256": "1639f4810fb5946b24e782b3ce463c000222dcac75709e1e3dac78ad4a2ad72f"
     },
+    {
+      "path": "skills/analyze-stats/references/analysis_guides/survival.md",
+      "size": 7191,
+      "sha256": "6b7f220f2aa165fd16eda58b0b40ac743c122c03757bc00f61efc884b203f337"
+    },
     {
       "path": "skills/analyze-stats/references/analysis_guides/test_selection.md",
       "size": 3439,
@@ -2953,8 +2968,8 @@
     },
     {
       "path": "skills/peer-review/references/domain-probes/diagnostic_accuracy.md",
-      "size": 11692,
-      "sha256": "afc69e56578babcc1cf7c7952d2df301fdc829329fb480a5cf426ff6ab65d9f5"
+      "size": 11967,
+      "sha256": "8c0a8bd30fe16507e2997ddba1bbcfb4ee7eade7df44f1981e1427cd3a28d233"
     },
     {
       "path": "skills/peer-review/references/domain-probes/equity_fairness.md",
@@ -3043,8 +3058,8 @@
     },
     {
       "path": "skills/peer-review/references/domain-probes/survival_prognostic.md",
-      "size": 13765,
-      "sha256": "af0e0323876424eec8ba07be22fe99b3100356e8e4895b5b79635e9a2d76e98e"
+      "size": 14297,
+      "sha256": "32cd929ff2e151f33bc5b106eddef0d38d5bd15672054e690c603ee82a22a817"
     },
     {
       "path": "skills/peer-review/references/exemplar_reviews/README.md",
@@ -3513,8 +3528,8 @@
     },
     {
       "path": "skills/self-review/references/domain-probes/diagnostic_accuracy.md",
-      "size": 11692,
-      "sha256": "afc69e56578babcc1cf7c7952d2df301fdc829329fb480a5cf426ff6ab65d9f5"
+      "size": 11967,
+      "sha256": "8c0a8bd30fe16507e2997ddba1bbcfb4ee7eade7df44f1981e1427cd3a28d233"
     },
     {
       "path": "skills/self-review/references/domain-probes/equity_fairness.md",
@@ -3603,8 +3618,8 @@
     },
     {
       "path": "skills/self-review/references/domain-probes/survival_prognostic.md",
-      "size": 13765,
-      "sha256": "af0e0323876424eec8ba07be22fe99b3100356e8e4895b5b79635e9a2d76e98e"
+      "size": 14297,
+      "sha256": "32cd929ff2e151f33bc5b106eddef0d38d5bd15672054e690c603ee82a22a817"
     },
     {
       "path": "skills/self-review/references/exemplar_findings/README.md",
@@ -3908,8 +3923,8 @@
     },
     {
       "path": "skills/write-paper/SKILL.md",
-      "size": 66771,
-      "sha256": "1a50c9ceb040a79feaa60e809c7196f9f04b85cab2f5f3402dcaed3f7aee552c"
+      "size": 67054,
+      "sha256": "62b3cbff56a139ed20a783c462fb6dde6b7a932bb057762a2d1c6382c8d044c1"
     },
     {
       "path": "skills/write-paper/references/exemplar_abstract.md",
@@ -3928,8 +3943,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",
@@ -3951,6 +3966,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,
@@ -3958,8 +3978,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",
@@ -3981,10 +4001,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",
@@ -4006,6 +4031,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.12.0",
+  "version": "5.14.0",
   "owned_skills": [
     "academic-aio",
     "add-journal",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "medsci-skills",
-  "version": "5.12.0",
+  "version": "5.14.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

@@ -393,6 +393,7 @@ tbl %>% as_flex_table() %>% flextable::save_as_docx(path = "table.docx")
 
 ### Diagnostic Accuracy
 
+- **Methodology guide**: `references/analysis_guides/diagnostic_accuracy.md` (**load before generating code** — every metric with a CI on a stated analysis unit; the confidence-weighted trap [unweighted-baseline AUC + monotonic-encoding check, produce-side of probe D9]; paired DeLong vs MRMC for reader-generalising claims; per-stratum admissibility [D10]; one-scale-per-comparison [D11])
 - Template: `references/templates/diagnostic_accuracy.py`
 - Always report: sensitivity, specificity, PPV, NPV, accuracy, AUC
 - CIs: Wilson score for proportions, DeLong for AUC
@@ -487,6 +488,7 @@ tbl %>% as_flex_table() %>% flextable::save_as_docx(path = "table.docx")
 
 ### Survival Analysis
 
+- **Methodology guide**: `references/analysis_guides/survival.md` (**load before generating code** — competing risks first [naive 1−KM overestimates → produce the Aalen–Johansen/Fine–Gray CIF; cause-specific vs subdistribution for which question, produce-side of probe S3]; PH check → RMST when violated; reverse-KM follow-up + C-index variant [S6]; estimand provenance [S8])
 - Table type guide: `references/table-standards/table-types/survival_results.md` (Cox results table: events/person-time, reverse-KM median follow-up, univariable + adjusted HR with CI, PH-assumption footnote, EPV/sparse-stratum and RMST-when-PH-violated rules)
 - Kaplan-Meier curves with number-at-risk table
 - Log-rank test for group comparison
@@ -543,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.

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

@@ -0,0 +1,184 @@
+# Diagnostic Accuracy & Reader-Study Guide
+
+Estimating how well an index test (or an AI model / reader) separates disease from
+no-disease against a reference standard. The point estimates are easy to compute; the
+ways these analyses fail review are (1) reporting AUC / sensitivity / specificity **without
+CIs or on the wrong analysis unit**, (2) a **confidence-weighted / rating** score whose
+novelty is never tested against the simpler **unweighted** baseline, and (3) comparing two
+AUCs with a **fixed-reader** test when the claim is meant to **generalise to readers**.
+
+---
+
+## When to Use
+
+- **Single index test** vs a reference standard → sensitivity, specificity, PPV, NPV, accuracy
+  (each with a 95% CI), and AUC (with a DeLong or bootstrap CI).
+- **Two tests / models on the same cases** → a **paired** AUC comparison (DeLong `roc.test`,
+  `paired = TRUE`) — never two independent CIs eyeballed for overlap.
+- **Multi-reader multi-case (MRMC)** reader study (AI-vs-reader, modality comparison) → an
+  MRMC method (Obuchowski–Rockette / DBM) that carries **reader + case** variance; see
+  `table-standards/table-types/reader_study.md` and `make-figures` `exemplar_plots/mrmc_roc.md`.
+- NOT for: pooling accuracy across studies (that is a DTA meta-analysis — bivariate / HSROC via
+  `mada`; see the `/meta-analysis` DTA path); not for rater **agreement** (that is
+  `analysis_guides/agreement_reliability.md`).
+
+---
+
+## Every metric with a CI, on a stated analysis unit (the floor)
+
+A bare AUC / sensitivity / specificity is not reportable. Compute the CI, and state the unit
+(**per-patient vs per-lesion** — multiple lesions per patient are clustered, exactly as in
+`agreement_reliability.md`; a per-lesion count inflates *n*).
+
+```python
+import numpy as np, pandas as pd
+from sklearn.metrics import roc_auc_score
+from statsmodels.stats.proportion import proportion_confint
+
+df = pd.read_csv("reader_calls.csv")   # truth (0/1), call (0/1), confidence (1..K), stratum
+
+# sensitivity / specificity / PPV / NPV at the operating point, each with a Wilson CI
+tp = int(((df.truth == 1) & (df.call == 1)).sum()); fn = int(((df.truth == 1) & (df.call == 0)).sum())
+tn = int(((df.truth == 0) & (df.call == 0)).sum()); fp = int(((df.truth == 0) & (df.call == 1)).sum())
+for name, num, den in [("sensitivity", tp, tp+fn), ("specificity", tn, tn+fp),
+                       ("PPV", tp, tp+fp), ("NPV", tn, tn+fn)]:
+    lo, hi = proportion_confint(num, den, method="wilson")
+    print(f"{name} = {num/den:.3f} (95% CI {lo:.3f}-{hi:.3f}), n={den}")
+```
+
+PPV and NPV are **prevalence-dependent** — do not transport them to a population with a
+different base rate; report sensitivity/specificity (prevalence-invariant) plus the study
+prevalence, and recompute predictive values at the target prevalence with Bayes' rule.
+
+---
+
+## The confidence-weighted trap comes first (this, not the AUC, is the issue)
+
+When the novelty is a **confidence-weighted / rating-collapsed** score used as the ROC
+predictor, you must (a) confirm the (call × confidence) encoding is **strictly monotone** — a
+folded encoding silently collides the most-confident-positive with a negative call — and
+(b) report the **unweighted binary-call AUC** beside the weighted one, so the weighting earns
+its place. This is the produce-side of self-review / peer-review probe **D9**.
+
+```python
+K = int(df.confidence.max())
+
+# intended strictly-monotone composite: negative calls rank below positive calls, and within
+# a call higher confidence pushes further from the decision boundary.
+def composite(call, conf, K):
+    return np.where(call == 1, K + conf, K + 1 - conf)   # neg: 1..K, pos: K+1..2K
+
+# (1) MONOTONIC-ENCODING CHECK — every distinct (call, confidence) must map to a distinct,
+#     correctly-ordered score. A collision is the folded-score bug (e.g. real/1 == ai/1).
+combos = df[["call", "confidence"]].drop_duplicates().copy()
+combos["score"] = composite(combos.call.values, combos.confidence.values, K)
+if combos.score.nunique() != len(combos):
+    raise ValueError("ENCODING COLLISION — the confidence weighting is not strictly monotone "
+                     "(folded-score bug); fix the encoding before computing AUC.")
+
+# (2) UNWEIGHTED BASELINE beside the weighted primary
+df["score"] = composite(df.call.values, df.confidence.values, K)
+print(f"AUC (confidence-weighted) = {roc_auc_score(df.truth, df.score):.3f}")
+print(f"AUC (unweighted binary call) = {roc_auc_score(df.truth, df.call):.3f}")
+```
+
+If the weighted AUC materially exceeds the unweighted one, the weighting must be justified;
+if it does not, report the simpler estimator as primary. A weighted score that changed a
+hypothesis's direction versus its unweighted baseline is a **post-lock change to disclose**,
+not a silent primary.
+
+---
+
+## AUC confidence intervals and comparing two AUCs
+
+DeLong is the field-standard analytic AUC CI and paired comparison; `pROC` (R) is canonical.
+
+```r
+library(pROC)
+d  <- read.csv("reader_calls.csv")
+rw <- roc(d$truth, d$score, quiet = TRUE)
+ci.auc(rw)                                   # DeLong 95% CI for the weighted AUC
+ru <- roc(d$truth, d$call,  quiet = TRUE)
+roc.test(rw, ru, method = "delong", paired = TRUE)   # paired, SAME cases (fixed-reader)
+```
+
+A portable Python bootstrap CI (use when a DeLong implementation is unavailable):
+
+```python
+def auc_ci_bootstrap(y, s, n_boot=2000, seed=42):
+    rng = np.random.default_rng(seed); y = np.asarray(y); s = np.asarray(s); n = len(y)
+    boots = [roc_auc_score(y[i], s[i]) for i in (rng.integers(0, n, n) for _ in range(n_boot))
+             if len(np.unique(y[i])) == 2]
+    return tuple(np.percentile(boots, [2.5, 97.5]))
+```
+
+**Fixed-reader vs MRMC.** A paired DeLong test treats the readers/cases as fixed. If the claim
+is that the result **generalises to readers** (a reader sample), a fixed-reader CI understates
+uncertainty — use an MRMC method (Obuchowski–Rockette / DBM) that carries reader + case
+variance, report per-reader and reader-averaged AUC, and state the unit (per-patient vs
+per-lesion) and the superiority/non-inferiority margin. This is probe D9's MRMC lead.
+
+---
+
+## Per-stratum admissibility: produce the table the claim is checked against (D10)
+
+A blanket "no subgroup met AUC ≥ 0.75 with lower bound ≥ 0.70" is falsified by a single tabled
+stratum that meets it. Produce the per-stratum AUC + CI and test each row against the rule
+rather than asserting a global negative.
+
+```python
+rule = lambda auc, lo: (auc >= 0.75) and (lo >= 0.70)
+for name, g in df.groupby("stratum"):
+    if g.truth.nunique() < 2:                       # single-class stratum: not estimable
+        print(f"{name}: not estimable (one class)"); continue
+    auc = roc_auc_score(g.truth, g.score); lo, hi = auc_ci_bootstrap(g.truth, g.score)
+    print(f"{name}: AUC {auc:.3f} (95% CI {lo:.3f}-{hi:.3f}) "
+          f"{'QUALIFIES' if rule(auc, lo) else 'below'}")
+```
+
+With *k* strata some crossings are expected — frame qualifying strata as hypothesis-generating
+(note the multiplicity), but do **not** deny a row the paper's own table satisfies.
+
+---
+
+## One scale per comparison (D11)
+
+Two values sharing a comparison column (or a row-wise "A vs B") must be computed under the
+**same normalisation / definition** — e.g. both volume errors as a standard relative error, not
+one relative and one range-normalised. If they are not identical, recompute on a common scale
+before any superiority/comparability claim, or footnote "not on the same scale".
+
+---
+
+## Reporting
+
+- Sensitivity, specificity, PPV, NPV, accuracy, and AUC each **with a 95% CI**; the operating
+  point and how it was chosen (Youden vs a prespecified clinical threshold — a threshold picked
+  on the same data is optimistic and needs a held-out or cross-validated estimate).
+- The **analysis unit** (per-patient vs per-lesion) and clustering handling; study prevalence.
+- For a weighted-score primary: the **unweighted-baseline AUC** beside it (D9).
+- AUC alone is insufficient for a clinical claim — pair discrimination with **calibration** and a
+  **decision-curve / net-benefit** pass at the relevant threshold (see the incremental-value
+  table type and the `make-figures` decision-curve exemplar).
+
+---
+
+## Common failures (flag at review)
+
+- **AUC / sensitivity / specificity with no CI**, or a per-lesion count reported as if per-patient.
+- **Confidence-weighted AUC with no unweighted baseline** and no monotonic-encoding check (D9) —
+  the weighting may have created the result or hidden a folded-score bug.
+- **Two AUCs compared by CI overlap** instead of a paired DeLong test; a **fixed-reader** CI used
+  for a claim that generalises to readers (needs MRMC).
+- **"No stratum met the rule" contradicted by the per-stratum table** (D10).
+- **Mixed-normalisation head-to-head** in one column (D11).
+- **PPV/NPV transported** across a prevalence change.
+
+---
+
+## Anti-Hallucination
+
+- Never hand-type an AUC, sensitivity/specificity, or CI — compute it from the calls CSV with a
+  seeded script; carry each estimate together with its CI (never a bare AUC).
+- Do not report a weighted-score AUC without the unweighted baseline the code produced.
+- Do not quote a DeLong comparison p-value that a paired test on the same cases did not produce.

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

@@ -0,0 +1,149 @@
+# Survival / Time-to-Event Guide
+
+Estimating time-to-event outcomes and prognostic effects. The estimator is easy to
+call; the ways these analyses fail review are (1) ignoring **competing risks** so a naive
+1−KM **overestimates** the cumulative incidence, (2) reporting a **single time-averaged
+hazard ratio** when the proportional-hazards assumption is violated, and (3) **estimand
+drift** — quoting a subdistribution hazard for an etiologic claim or a cause-specific hazard
+for an absolute-risk claim. This guide produces the right estimand; the operational caveats
+(EPV gate, cluster-robust CIs, interval-censoring) live in the SKILL.md `### Survival
+Analysis` section.
+
+---
+
+## When to Use
+
+- **Single event type, right-censored** → Kaplan–Meier (unadjusted) + Cox proportional-hazards
+  (adjusted HR with 95% CI); the log-rank test for a KM group comparison.
+- **≥2 competing event types** (recurrence + competing death, or cause-specific mortality) →
+  cumulative incidence functions + **cause-specific Cox** or **Fine–Gray** — see below.
+- **Prognostic model discrimination** → a C-index variant matched to the censoring + a
+  time-dependent AUC at a clinical horizon (S6).
+- NOT for: events detected only at scheduled visits → interval-censored methods (SKILL.md);
+  recurrent events per subject → a cluster-robust or frailty model (SKILL.md cluster rule);
+  rater agreement → `analysis_guides/agreement_reliability.md`.
+
+---
+
+## Competing risks come first (this, not the HR, is the issue)
+
+If a subject can experience an event that **precludes** the event of interest (death before
+recurrence), treating the competing event as ordinary censoring is *informative* censoring:
+the naive **1−KM overestimates** the cumulative incidence of the event of interest. Produce the
+**cumulative incidence function (CIF)** with an Aalen–Johansen / Fine–Gray estimator instead.
+This is the produce-side of probe **S3**.
+
+```python
+# lifelines: cumulative incidence for a competing-risks event of interest
+from lifelines import AalenJohansenFitter, KaplanMeierFitter
+import pandas as pd
+df = pd.read_csv("survival.csv")   # time, event_type (0=censored, 1=interest, 2=competing)
+
+ajf = AalenJohansenFitter()
+ajf.fit(df["time"], df["event_type"], event_of_interest=1)
+print(ajf.cumulative_density_.tail(1))          # correct CIF for cause 1
+
+kmf = KaplanMeierFitter()                        # NAIVE (cause 2 censored) — overestimates
+kmf.fit(df["time"], (df["event_type"] == 1).astype(int))
+print("naive 1-KM:", float(1 - kmf.survival_function_.iloc[-1, 0]))
+# the naive value will exceed the Aalen-Johansen CIF whenever the competing event is common.
+```
+
+**Which model for which question (S8 estimand):**
+
+- **Cause-specific hazard** (a Cox model that censors the competing event) answers an
+  **etiologic** question — "does X change the rate of recurrence among those still at risk?"
+- **Fine–Gray subdistribution hazard** (`cmprsk::crr` / `survival::finegray` in R) answers a
+  **prognostic / absolute-risk** question — "does X change the cumulative *incidence*?" Quote an
+  sHR for an incidence claim and a cause-specific HR for an etiologic claim — not the reverse.
+
+```r
+library(survival)                       # Fine-Gray via a weighted Cox on the finegray split
+fg  <- finegray(Surv(time, factor(event_type)) ~ ., data = d, etype = 1)
+crr <- coxph(Surv(fgstart, fgstop, fgstatus) ~ x, weight = fgwt, data = fg)   # subdistribution HR
+```
+
+---
+
+## Proportional hazards, and RMST when it fails
+
+A single Cox HR is a time-average; if PH is violated it averages a changing effect. Test PH,
+and when it fails report a **restricted mean survival time (RMST) difference** at a fixed
+horizon (an estimand that stays interpretable under non-PH) rather than one HR.
+
+```python
+from lifelines import CoxPHFitter
+cph = CoxPHFitter().fit(df, "time", "event")
+cph.check_assumptions(df, p_value_threshold=0.05)   # Schoenfeld; significant -> PH violated
+```
+
+```r
+library(survRM2)
+rmst2(time, status, arm, tau = 3)   # RMST difference at tau=3 years, valid under non-PH
+```
+
+Do not report a single time-averaged HR alongside a significant Schoenfeld test without also
+giving a piecewise/time-stratified HR or an RMST difference (SKILL.md PH-violation rule).
+
+---
+
+## Follow-up and discrimination (S6)
+
+- **Reverse Kaplan–Meier median follow-up** — the honest "how long were people followed"
+  (median event time answers a different question). Compute it by **swapping the event
+  indicator** (censored observations become the "events"); report it per cohort and per
+  outcome, with the censoring date.
+
+```python
+kmf.fit(df["time"], 1 - df["event"])            # swap: censored -> event
+print("reverse-KM median follow-up:", kmf.median_survival_time_)
+```
+
+- **C-index variant** — Harrell's C is biased under heavy or non-random censoring; report
+  **Uno's IPCW C** (`survC1::Est.Cval` / `timeROC`) and a **time-dependent AUC at a clinical
+  horizon** (2-/3-year) beside it, and state which variant and horizon (S6).
+
+---
+
+## Estimand provenance (S8)
+
+State the survival estimand explicitly and hold it consistent across Abstract / Methods /
+Results — event-free survival vs cause-specific cumulative incidence vs all-cause mortality,
+and subject vs population level — with the evaluation horizon fixed in advance. Do not
+re-designate the primary endpoint, model, or horizon after seeing results, and make every
+derived statistic (an E-value, an sHR-vs-cause-specific contrast) trace to the *declared
+primary* estimand. The self-review skill automates the registration ↔ manuscript and E-value
+arithmetic checks (Phase 2.5f); see also `estimand-provenance-lock`.
+
+---
+
+## Reporting
+
+- KM curves **with a number-at-risk table**; median survival with 95% CI (or the reason it is
+  not reached).
+- Cox HR (95% CI) with the **PH check stated**; for competing risks, the CIF and whether the
+  HR is cause-specific or subdistribution.
+- Events and person-time per group; the **reverse-KM median follow-up**; EPV for the model.
+- The estimand and horizon, stated once and consistent everywhere.
+
+---
+
+## Common failures (flag at review)
+
+- **Competing risks ignored** — naive 1−KM (or a cause-specific model presented as absolute
+  risk) overestimates incidence; report a CIF and name cause-specific vs subdistribution (S3/S8).
+- **A single time-averaged HR under a violated PH assumption** — needs a piecewise HR or RMST.
+- **Harrell's C under heavy censoring** with no Uno/IPCW variant and no horizon (S6).
+- **Median *survival* reported as "follow-up"** instead of the reverse-KM follow-up.
+- **Estimand drift** — a primary endpoint/model/horizon re-designated post-hoc, or a derived
+  statistic quoted off a non-primary estimate (S8).
+
+---
+
+## Anti-Hallucination
+
+- Never hand-type an HR, median, CIF, or CI — compute it from the time-to-event CSV with a
+  seeded script, and carry each estimate together with its CI.
+- Do not report a Cox HR without the proportional-hazards check the code actually ran.
+- Under competing risks, do not quote a 1−KM cumulative incidence — report the Aalen–Johansen /
+  Fine–Gray CIF the code produced.

package/skills/peer-review/references/domain-probes/diagnostic_accuracy.md

@@ -47,6 +47,7 @@ A checklist for **diagnostic test accuracy (DTA) primary studies** — an index
 - When a reader study's novelty is a **confidence-weighted** (or rating-collapsed) score used as the ROC/AUC predictor, the **unweighted binary-call AUC** must be reported side-by-side (as a sensitivity analysis). Without it, you cannot tell whether the weighting *created* the result or hid an estimator fragility (e.g. a folded/non-monotonic encoding that collapses `real/5` with `ai/1`).
 - Lead: if the primary predictor is a confidence/rating→single-score collapse and no unweighted binary-call AUC appears, ask for it; also confirm the (call × confidence) encoding is strictly monotonic (no boundary collision) — the folded-score bug understates one hypothesis and can flip another.
 - Severity: MAJOR when the weighted score is the headline and no unweighted baseline is shown; the weighting must "earn its place" against the simpler estimator.
+- Produce the fix: `analyze-stats` `references/analysis_guides/diagnostic_accuracy.md` has the monotonic-encoding check + the unweighted-baseline AUC beside the weighted primary (and the per-stratum admissibility table for D10 and the one-scale-per-comparison rule for D11).
 
 **D10 — "No stratum met threshold X" vs a per-stratum table that does meet X**:
 - When the manuscript states a numeric admissibility/deployability rule (e.g. "AUC ≥ 0.75 **and** lower 95% bound ≥ 0.70") and concludes "**no stratum met** the rule" / "all strata were below", cross-check that claim against the **per-stratum AUC + CI table**. A blanket negative-stratum claim contradicted by a tabled stratum that literally satisfies the rule (e.g. ultrasound 0.789, CI 0.742–0.834) is a self-contradiction a reviewer verifies with arithmetic.

package/skills/peer-review/references/domain-probes/survival_prognostic.md

@@ -28,6 +28,7 @@ A 9-probe checklist for time-to-event outcomes and prognostic model development.
 - Cause-specific hazards or Fine-Gray subdistribution hazards used?
 - Patient developing one event still at risk for the other (informative censoring by death)?
 - If competing-risks structure is ignored and outcomes are treated as independent right-censored events → MAJOR.
+- Produce the fix: `analyze-stats` `references/analysis_guides/survival.md` has the Aalen–Johansen/Fine–Gray cumulative-incidence code (naive 1−KM overestimates) + the cause-specific-vs-subdistribution estimand choice (S8) and the PH→RMST fallback.
 
 **S4 — Cutoff derivation optimism**:
 - Cutoffs derived via maximally selected log-rank statistics, AUC-based Youden's J, or similar data-driven methods?
@@ -55,6 +56,7 @@ A 9-probe checklist for time-to-event outcomes and prognostic model development.
 - Decision-curve analysis at clinically relevant probability thresholds?
 - For a prognostic model intended to guide surveillance intensity, treatment intensification, or eligibility for adjuvant therapy, discrimination alone is insufficient. If Methods mention calibration but Results/supplement contain no calibration plot or numeric metrics → MAJOR.
 - **Apparent-vs-optimism-corrected deterministic tell**: discrimination/calibration reported with no internal-validation token nearby (`optimism`, `bootstrap`, `cross-valid`, `held-out`, `external`) is presumptively **apparent (in-sample) performance**. A **calibration slope reported as exactly 1.00** (and/or Uno's C, Brier, net-benefit all on the development sample) is the in-sample-fit signature — the model was evaluated on the data it was fit to. Flag MINOR (a bootstrap optimism correction is cheap and usually reproduces the estimate); escalate to MAJOR when the model is assessed for clinical utility / net-benefit, where optimistic metrics directly inflate the deployment claim.
+- Produce the fix: `analyze-stats` `references/analysis_guides/calibration.md` has the bootstrap optimism-corrected calibration slope/intercept (the apparent slope is 1.00 by construction), the flexible calibration curve + scaled Brier, and why Hosmer–Lemeshow is dropped.
 
 **S8 — Estimand provenance**:
 - Is the survival estimand stated explicitly and held consistent across Abstract / Methods / Results — event-free survival, cause-specific cumulative incidence, all-cause mortality — and at the subject vs population level? A subdistribution hazard (Fine-Gray) answers a different question than a cause-specific hazard; quoting an sHR for an etiologic claim, or a cause-specific HR for an absolute-risk claim, is an estimand mismatch.

package/skills/self-review/references/domain-probes/diagnostic_accuracy.md

@@ -47,6 +47,7 @@ A checklist for **diagnostic test accuracy (DTA) primary studies** — an index
 - When a reader study's novelty is a **confidence-weighted** (or rating-collapsed) score used as the ROC/AUC predictor, the **unweighted binary-call AUC** must be reported side-by-side (as a sensitivity analysis). Without it, you cannot tell whether the weighting *created* the result or hid an estimator fragility (e.g. a folded/non-monotonic encoding that collapses `real/5` with `ai/1`).
 - Lead: if the primary predictor is a confidence/rating→single-score collapse and no unweighted binary-call AUC appears, ask for it; also confirm the (call × confidence) encoding is strictly monotonic (no boundary collision) — the folded-score bug understates one hypothesis and can flip another.
 - Severity: MAJOR when the weighted score is the headline and no unweighted baseline is shown; the weighting must "earn its place" against the simpler estimator.
+- Produce the fix: `analyze-stats` `references/analysis_guides/diagnostic_accuracy.md` has the monotonic-encoding check + the unweighted-baseline AUC beside the weighted primary (and the per-stratum admissibility table for D10 and the one-scale-per-comparison rule for D11).
 
 **D10 — "No stratum met threshold X" vs a per-stratum table that does meet X**:
 - When the manuscript states a numeric admissibility/deployability rule (e.g. "AUC ≥ 0.75 **and** lower 95% bound ≥ 0.70") and concludes "**no stratum met** the rule" / "all strata were below", cross-check that claim against the **per-stratum AUC + CI table**. A blanket negative-stratum claim contradicted by a tabled stratum that literally satisfies the rule (e.g. ultrasound 0.789, CI 0.742–0.834) is a self-contradiction a reviewer verifies with arithmetic.

package/skills/self-review/references/domain-probes/survival_prognostic.md

@@ -28,6 +28,7 @@ A 9-probe checklist for time-to-event outcomes and prognostic model development.
 - Cause-specific hazards or Fine-Gray subdistribution hazards used?
 - Patient developing one event still at risk for the other (informative censoring by death)?
 - If competing-risks structure is ignored and outcomes are treated as independent right-censored events → MAJOR.
+- Produce the fix: `analyze-stats` `references/analysis_guides/survival.md` has the Aalen–Johansen/Fine–Gray cumulative-incidence code (naive 1−KM overestimates) + the cause-specific-vs-subdistribution estimand choice (S8) and the PH→RMST fallback.
 
 **S4 — Cutoff derivation optimism**:
 - Cutoffs derived via maximally selected log-rank statistics, AUC-based Youden's J, or similar data-driven methods?
@@ -55,6 +56,7 @@ A 9-probe checklist for time-to-event outcomes and prognostic model development.
 - Decision-curve analysis at clinically relevant probability thresholds?
 - For a prognostic model intended to guide surveillance intensity, treatment intensification, or eligibility for adjuvant therapy, discrimination alone is insufficient. If Methods mention calibration but Results/supplement contain no calibration plot or numeric metrics → MAJOR.
 - **Apparent-vs-optimism-corrected deterministic tell**: discrimination/calibration reported with no internal-validation token nearby (`optimism`, `bootstrap`, `cross-valid`, `held-out`, `external`) is presumptively **apparent (in-sample) performance**. A **calibration slope reported as exactly 1.00** (and/or Uno's C, Brier, net-benefit all on the development sample) is the in-sample-fit signature — the model was evaluated on the data it was fit to. Flag MINOR (a bootstrap optimism correction is cheap and usually reproduces the estimate); escalate to MAJOR when the model is assessed for clinical utility / net-benefit, where optimistic metrics directly inflate the deployment claim.
+- Produce the fix: `analyze-stats` `references/analysis_guides/calibration.md` has the bootstrap optimism-corrected calibration slope/intercept (the apparent slope is 1.00 by construction), the flexible calibration curve + scaled Brier, and why Hosmer–Lemeshow is dropped.
 
 **S8 — Estimand provenance**:
 - Is the survival estimand stated explicitly and held consistent across Abstract / Methods / Results — event-free survival, cause-specific cumulative incidence, all-cause mortality — and at the subject vs population level? A subdistribution hazard (Fine-Gray) answers a different question than a cause-specific hazard; quoting an sHR for an etiologic claim, or a cause-specific HR for an absolute-risk claim, is an estimand mismatch.

package/skills/write-paper/SKILL.md

@@ -221,7 +221,7 @@ Design all tables and figures BEFORE writing prose. This ensures the narrative s
 
 Write the Methods section first -- it is the most objective and anchors the rest of the paper.
 
-**Before writing:** Load `${CLAUDE_SKILL_DIR}/references/section_guides/methods.md` for PICO structure, backbone article usage, checklist cross-reference, and terminology conventions. For the matching study type, also skim the structure model in `${CLAUDE_SKILL_DIR}/references/exemplar_methods/` (diagnostic-accuracy/STARD, AI-validation/TRIPOD+AI·CLAIM, observational-cohort/STROBE, meta-analysis/PRISMA 2020) — it lists, paragraph by paragraph, what each Methods paragraph must establish plus the element that type most often omits. Model the structure; the exemplars are synthetic, with placeholder specifics, not prose to copy.
+**Before writing:** Load `${CLAUDE_SKILL_DIR}/references/section_guides/methods.md` for PICO structure, backbone article usage, checklist cross-reference, and terminology conventions. For the matching study type, also skim the structure model in `${CLAUDE_SKILL_DIR}/references/exemplar_methods/` (diagnostic-accuracy/STARD, AI-validation/TRIPOD+AI·CLAIM, observational-cohort/STROBE, meta-analysis/PRISMA 2020, RCT/CONSORT 2010) — it lists, paragraph by paragraph, what each Methods paragraph must establish plus the element that type most often omits. Model the structure; the exemplars are synthetic, with placeholder specifics, not prose to copy.
 
 **Writing order within Methods:**
 1. Study Design and Setting
@@ -255,7 +255,7 @@ Write the Methods section first -- it is the most objective and anchors the rest
 Write Results aligned to the approved tables and figures. **Results = "What did we find?"
 — nothing more.** Every sentence must be a factual statement backed by a number.
 
-**Before writing:** Load `${CLAUDE_SKILL_DIR}/references/section_guides/results.md` for mirror-symmetry rules, flowchart requirements, missing data handling, and the anti-interpretation self-check. For the matching study type, also skim the structure model in `${CLAUDE_SKILL_DIR}/references/exemplar_results/` (diagnostic-accuracy/STARD, AI-validation/TRIPOD+AI·CLAIM, observational-cohort/STROBE, meta-analysis/PRISMA 2020) — each follows its `exemplar_methods/` sibling in Methods order, listing what each Results paragraph must establish (flow → baseline/prevalence → primary estimate with CIs → calibration/agreement → subgroups → sensitivity; for meta-analysis, PRISMA flow → characteristics+provenance → RoB → pooled estimate with I²/τ²/prediction interval → subgroup interaction → publication bias) plus the element that type most often omits. Model the structure; the exemplars are synthetic, with placeholder specifics, not prose to copy.
+**Before writing:** Load `${CLAUDE_SKILL_DIR}/references/section_guides/results.md` for mirror-symmetry rules, flowchart requirements, missing data handling, and the anti-interpretation self-check. For the matching study type, also skim the structure model in `${CLAUDE_SKILL_DIR}/references/exemplar_results/` (diagnostic-accuracy/STARD, AI-validation/TRIPOD+AI·CLAIM, observational-cohort/STROBE, meta-analysis/PRISMA 2020, RCT/CONSORT 2010) — each follows its `exemplar_methods/` sibling in Methods order, listing what each Results paragraph must establish (flow → baseline/prevalence → primary estimate with CIs → calibration/agreement → subgroups → sensitivity; for meta-analysis, PRISMA flow → characteristics+provenance → RoB → pooled estimate with I²/τ²/prediction interval → subgroup interaction → publication bias; for an RCT, CONSORT flow → baseline-by-arm with no p-values → ITT primary with CI → secondary+harms → per-protocol beside ITT) plus the element that type most often omits. Model the structure; the exemplars are synthetic, with placeholder specifics, not prose to copy.
 
 **Rules:**
 - Every number in the text must match the corresponding table cell exactly.
@@ -296,7 +296,7 @@ Write Results aligned to the approved tables and figures. **Results = "What did
 
 ### Phase 5: Discussion
 
-**Before writing:** Load `${CLAUDE_SKILL_DIR}/references/section_guides/discussion.md` for the 4-paragraph structure, word limits, limitation writing guidelines, and Table/Figure citation rules. For the matching study type, also skim the structure model in `${CLAUDE_SKILL_DIR}/references/exemplar_discussion/` (diagnostic-accuracy/STARD, AI-validation/TRIPOD+AI·CLAIM, observational-cohort/STROBE, meta-analysis/PRISMA 2020) — completing the exemplar trio, each lists what every Discussion paragraph must establish (key finding → interpretation/comparison → limitations → generalizability → conclusion matched to the evidence) plus the element that type most often omits (spectrum/verification bias; evidence-tier separation and optimism caveats; mandatory causal caution; for meta-analysis, GRADE certainty + heterogeneity source + non-independence/overlap caveat). For case reports, use `${CLAUDE_SKILL_DIR}/references/exemplar_case_report.md` instead: it controls literature-boundary wording, n=1 causal caution, and bedside teaching-point framing. Model the structure; the exemplars are synthetic, introduce no new results, and are not prose to copy.
+**Before writing:** Load `${CLAUDE_SKILL_DIR}/references/section_guides/discussion.md` for the 4-paragraph structure, word limits, limitation writing guidelines, and Table/Figure citation rules. For the matching study type, also skim the structure model in `${CLAUDE_SKILL_DIR}/references/exemplar_discussion/` (diagnostic-accuracy/STARD, AI-validation/TRIPOD+AI·CLAIM, observational-cohort/STROBE, meta-analysis/PRISMA 2020, RCT/CONSORT 2010) — completing the exemplar trio, each lists what every Discussion paragraph must establish (key finding → interpretation/comparison → limitations → generalizability → conclusion matched to the evidence) plus the element that type most often omits (spectrum/verification bias; evidence-tier separation and optimism caveats; mandatory causal caution; for meta-analysis, GRADE certainty + heterogeneity source + non-independence/overlap caveat; for an RCT, blinding/attrition limitation + clinical-vs-statistical significance vs the MCID). For case reports, use `${CLAUDE_SKILL_DIR}/references/exemplar_case_report.md` instead: it controls literature-boundary wording, n=1 causal caution, and bedside teaching-point framing. Model the structure; the exemplars are synthetic, introduce no new results, and are not prose to copy.
 
 **Before drafting, collect user input (Discussion Planning Gate).**
 

package/skills/write-paper/references/exemplar_discussion/README.md

@@ -30,6 +30,8 @@ closes with a conclusion matched to the evidence — introducing no new results.
 - `meta_analysis_prisma.md` — summary-of-evidence with certainty framing, heterogeneity-source
   and non-independence/overlap caveats, GRADE limitations, no guideline-grade conclusion
   (PRISMA 2020).
+- `rct_consort.md` — primary-on-ITT key finding, clinical-vs-statistical significance vs the MCID,
+  blinding/attrition limitations, single-trial conclusion (CONSORT 2010).
 
 ## Curator guidelines (for adding more)
 

package/skills/write-paper/references/exemplar_discussion/rct_consort.md

@@ -0,0 +1,42 @@
+# Discussion structure — randomized controlled trial (CONSORT 2010)
+
+A structure model for the Discussion of a parallel-group RCT, completing the trio with the
+`exemplar_methods/` and `exemplar_results/` siblings. Each heading is a paragraph; each bullet is
+*what it must establish*. Fill the `[brackets]`; do not copy this text. Follows
+`section_guides/discussion.md`. Introduces **no new results** and cites **no tables/figures**.
+
+## Paragraph 1 — Key finding
+- Restate the **primary** result (the effect estimate + CI on the ITT population) in 2–3
+  sentences, matched to Results — no new estimate, and no elevation of a secondary outcome.
+- One sentence on clinical meaning, tied to the **pre-stated MCID** (a statistically significant
+  effect smaller than the MCID is not clinically meaningful).
+- **If the primary is null or non-inferiority is not shown, frame it by the CI vs the margin**,
+  not as "no difference" — state what the interval excludes.
+
+## Paragraphs 2–3 — Interpretation and comparison
+- Compare to prior trials and meta-analyses (agree / differ and why: population, comparator,
+  dose, endpoint); avoid over-generalizing beyond the enrolled population.
+- Discuss mechanism / plausibility as hypothesis; keep secondary and subgroup findings explicitly
+  exploratory (do not narrate a subgroup as if it were a confirmatory result).
+
+## Limitations
+- **Risk-of-bias honesty**: open-label / unblinded assessment, attrition and how missing primary
+  data were handled, any post-randomization exclusions, early stopping and its effect on the
+  estimate, single-centre / narrow eligibility limiting external validity.
+- Whether the trial was powered for the primary only (secondary/subgroup analyses under-powered).
+
+## Generalizability
+- The population and setting the result applies to, and where it may not transfer (eligibility
+  restrictions, standard-of-care comparator specific to the setting, adherence in a trial vs
+  routine care).
+
+## Conclusion
+- Matched to the evidence — a single trial supports the primary contrast in the studied
+  population; use "in this trial, [intervention] reduced/did not reduce [outcome]", not a
+  guideline-grade recommendation the evidence tier does not license.
+
+## Common omission
+- An explicit **blinding / attrition limitation and a clinical-vs-statistical-significance caveat**
+  tied to the MCID — the Discussion elements RCT drafts most often soften. Cross-reference
+  `section_guides/discussion.md`, the `peer-review/references/domain-probes/rct_trial.md` probes,
+  and, for an AI intervention, the CONSORT-AI reporting items.

package/skills/write-paper/references/exemplar_methods/README.md

@@ -24,6 +24,7 @@ fit). A missing element is a gap to fill before drafting Results.
 - `ai_validation_tripod_claim.md` — an AI/ML model development + validation study (TRIPOD+AI / CLAIM).
 - `observational_cohort_strobe.md` — an exposure→outcome observational cohort (STROBE).
 - `meta_analysis_prisma.md` — a systematic review with quantitative synthesis (PRISMA 2020).
+- `rct_consort.md` — a parallel-group randomized controlled trial (CONSORT 2010).
 
 ## Curator guidelines (for adding more)
 

package/skills/write-paper/references/exemplar_methods/rct_consort.md

@@ -0,0 +1,55 @@
+# Methods structure — randomized controlled trial (CONSORT 2010)
+
+A structure model for a parallel-group RCT. Each heading is a paragraph; each bullet is *what it
+must establish*. Fill the `[brackets]`; do not copy this text. Anchors to CONSORT 2010; pairs the
+`peer-review/references/domain-probes/rct_trial.md` probes (and CONSORT-AI/SPIRIT-AI for an AI
+intervention).
+
+## Trial design and registration
+- Design (parallel-group / crossover / cluster), allocation ratio (e.g. 1:1), and framework
+  (superiority / non-inferiority / equivalence) — with the **margin** stated up front for the
+  latter two.
+- **Prospective trial registration** (ClinicalTrials.gov / a WHO ICTRP registry) with the number,
+  and the protocol reference; ethics approval and informed consent.
+
+## Participants, setting, interventions
+- Eligibility as a numbered inclusion / exclusion list; the settings and the recruitment and
+  follow-up dates.
+- The experimental and comparator interventions in enough detail to replicate (dose, schedule,
+  who delivered them); the comparator is a real, defined control (placebo / standard-of-care),
+  not a strawman.
+
+## Outcomes
+- The **single pre-specified primary outcome** with its metric and time point (do not re-designate
+  the primary after seeing data); secondary outcomes listed; any changes to outcomes after trial
+  commencement disclosed with dates.
+
+## Sample size
+- The power calculation: assumed effect (the MCID, not the hoped-for effect), α, power, and the
+  resulting N with attrition inflation; for non-inferiority, the margin and its justification.
+
+## Randomization, allocation concealment, blinding
+- **Sequence generation** (how the random sequence was produced), **allocation concealment**
+  (the mechanism that hid the next assignment — central/pharmacy/sealed opaque envelopes), and
+  **implementation** (who enrolled, who assigned) — three distinct items, all required.
+- **Blinding**: who was blinded (participants, clinicians, outcome assessors, analysts) and how;
+  if open-label, state it and how assessor blinding was preserved.
+
+## Statistical methods
+- The primary analysis and estimand: the contrast, the population (**intention-to-treat** as
+  primary — everyone as randomized; per-protocol as a secondary, and the primary population for a
+  non-inferiority trial stated), and how missing data were handled (not naive complete-case for a
+  dropout-prone endpoint).
+- Pre-specified subgroups and interim analyses / stopping rules; multiplicity handling; software.
+
+## Reporting-guideline fit
+- CONSORT 2010 (+ CONSORT-AI for an AI intervention). Critical items: registration, sequence
+  generation + allocation concealment + blinding, the pre-specified primary, ITT, and a
+  participant flow diagram that reconciles (randomized → received → analyzed).
+
+## Common omission
+- **Allocation concealment described as blinding** (they are different — concealment protects
+  *assignment*, blinding protects *ascertainment*), and an unstated **ITT vs per-protocol**
+  primary population — the Methods elements RCT drafts most often conflate or skip, and the first
+  a trials reviewer checks. Cross-reference `section_guides/methods.md` and the
+  `peer-review/references/domain-probes/rct_trial.md` probes.

package/skills/write-paper/references/exemplar_results/README.md

@@ -30,6 +30,8 @@ element that interprets rather than reports belongs in the Discussion.
 - `meta_analysis_prisma.md` — PRISMA flow, study/patient characteristics + provenance, pooled
   estimate with I²/τ²/prediction interval, subgroup interaction, sensitivity, publication bias
   (PRISMA 2020).
+- `rct_consort.md` — CONSORT flow, baseline by arm (no p-values), ITT primary estimate with CI,
+  secondary outcomes + harms, subgroup interaction, per-protocol beside ITT (CONSORT 2010).
 
 ## Curator guidelines (for adding more)
 

package/skills/write-paper/references/exemplar_results/rct_consort.md

@@ -0,0 +1,38 @@
+# Results structure — randomized controlled trial (CONSORT 2010)
+
+A structure model for the Results of a parallel-group RCT. It follows its Methods CONSORT
+sibling in Methods order. Each heading is a paragraph; each bullet is *what it must establish*.
+Fill the `[brackets]`; do not copy this text. Report findings only — no interpretation.
+
+## Participant flow (Figure 1 — CONSORT diagram)
+- The CONSORT flow: assessed → randomized → allocated (received / did not receive) → followed up
+  (lost, discontinued, with reasons) → analyzed, **per arm**, with counts.
+- The cascade reconciles (randomized = Σ analyzed + Σ excluded-with-reason); the number
+  **analyzed for the primary outcome** matches the ITT denominator. Numbers match the Abstract,
+  Methods, and Table 1.
+
+## Recruitment and baseline (Table 1)
+- Recruitment and follow-up dates and why the trial ended (target reached / stopped);
+  Table 1 baseline characteristics **by arm** — **no p-values for baseline balance** (randomization
+  makes them meaningless; show the descriptive comparison and, if used, the balance metric).
+
+## Primary outcome
+- The pre-specified **primary** outcome by arm: the **effect estimate with its 95% CI** and the
+  absolute numbers per arm (events/N or mean±SD), on the **ITT** population — not just a p-value.
+- For non-inferiority: the CI relative to the **pre-stated margin** (the conclusion follows from
+  where the CI sits, not from a significance test).
+
+## Secondary outcomes and harms
+- Secondary outcomes with estimates + CIs, flagged as secondary (multiplicity in view — do not
+  elevate a significant secondary to a headline).
+- **Harms / adverse events** reported per arm (a trial that reports only efficacy is incomplete).
+
+## Subgroups and sensitivity
+- Pre-specified subgroup analyses with the **interaction test**, framed as exploratory; the
+  per-protocol analysis beside ITT (concordance is reassuring; divergence is discussed, not hidden).
+
+## Common omission
+- **Baseline p-values** (should not appear), and the **primary reported off the per-protocol set**
+  rather than ITT, or without its absolute per-arm numbers — the Results elements RCT drafts most
+  often get wrong. Cross-reference `section_guides/results.md`, the
+  `peer-review/references/domain-probes/rct_trial.md` probes, and the CONSORT flow requirement.