medsci-skills 5.13.0 → 5.14.0

package/metadata/distribution_files.json

@@ -153,14 +153,19 @@
     },
     {
       "path": "skills/analyze-stats/SKILL.md",
-      "size": 56422,
-      "sha256": "ddb73598fe60601942e8b44a87771e3ba583a585304effac4ae206d53ab4f154"
+      "size": 56948,
+      "sha256": "e7f01164e2fc9db924e49ee226b13bcf78d4d7c0463099c0f666985152a91d2e"
     },
     {
       "path": "skills/analyze-stats/references/analysis_guides/agreement_reliability.md",
       "size": 6674,
       "sha256": "599ad2551f547043b2bec79e3139d9c2c3ae33c5025784359b22022f882504c2"
     },
+    {
+      "path": "skills/analyze-stats/references/analysis_guides/calibration.md",
+      "size": 6470,
+      "sha256": "ac33862c6c707997be5a2511ed6a6d546c1e829fc9fc033d1c85eca9afa3ca9a"
+    },
     {
       "path": "skills/analyze-stats/references/analysis_guides/diagnostic_accuracy.md",
       "size": 9303,
@@ -3053,8 +3058,8 @@
     },
     {
       "path": "skills/peer-review/references/domain-probes/survival_prognostic.md",
-      "size": 14022,
-      "sha256": "96195cd1b575535bc12a133125b9d85e2ca7e756b96a0649e03d4c3696e5312b"
+      "size": 14297,
+      "sha256": "32cd929ff2e151f33bc5b106eddef0d38d5bd15672054e690c603ee82a22a817"
     },
     {
       "path": "skills/peer-review/references/exemplar_reviews/README.md",
@@ -3613,8 +3618,8 @@
     },
     {
       "path": "skills/self-review/references/domain-probes/survival_prognostic.md",
-      "size": 14022,
-      "sha256": "96195cd1b575535bc12a133125b9d85e2ca7e756b96a0649e03d4c3696e5312b"
+      "size": 14297,
+      "sha256": "32cd929ff2e151f33bc5b106eddef0d38d5bd15672054e690c603ee82a22a817"
     },
     {
       "path": "skills/self-review/references/exemplar_findings/README.md",
@@ -3918,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",
@@ -3938,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",
@@ -3961,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,
@@ -3968,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",
@@ -3991,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",
@@ -4016,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.13.0",
+  "version": "5.14.0",
   "owned_skills": [
     "academic-aio",
     "add-journal",

package/package.json

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

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

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

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

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

@@ -56,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/survival_prognostic.md

@@ -56,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.