aperivue/design-study
> Study design and validity review for radiology and medical AI research. Identifies analysis unit, cohort logic, leakage risks, comparator design, validation strategy, and reporting guideline fit before drafting or submission.
npx skills add https://github.com/Aperivue/medsci-skills --skill design-study
This skill pressure-tests whether a study is answerable, interpretable, and defensible before large amounts of drafting or analysis work accumulate.
Use it when:
Always inspect these dimensions:
10. Which reporting guideline best fits?
11. Are exposure/outcome/covariate definitions literature-grounded, or invented ad-hoc from the data dictionary? If ad-hoc, defer to /define-variables before drafting Methods.
## Study Design Review
Question: ...
Study type: ...
Analysis unit: ...
Index date / prediction timepoint: ...
### Strengths
- ...
### Major validity risks
1. ...
2. ...
### Minimal fixes
- ...
### Reporting fit
- Recommended guideline: ...
### Decision
- Ready for analysis / Needs redesign / Drafting can proceed with limitations
Extract from protocol, draft, slides, tables, or notes:
Gate: Present the reconstructed study summary (question, analysis unit, intended use)
to the user. Confirm before proceeding — if the reconstruction is wrong, the entire
validity review will be misdirected.
Look for mismatches such as:
Look for:
sections such as clinical history, indication, impression, prior diagnosis, or referral text, confirm
that those fields do not literally name or strongly imply the target label. If the target is already
present in the supplied text, the task is information retrieval under label leakage, not phenotype
inference; redesign the input mask, report a sensitivity analysis excluding leaky fields, or reframe the
claim.
(i) *mathematical definition* — an input that computes the outcome (when the outcome is HOMA-IR =
f(fasting insulin, fasting glucose), those two inputs are not independent predictors); (ii)
*near-tautological composite* — a ratio or score built from the outcome's defining components, which
shows an inflated, near-circular association. Test: "could this predictor be derived, in whole or
part, from the outcome's definition or the same measurement?" If yes, exclude it, or retain it only
as a labeled calibration probe rather than a reported discovery.
For any time-to-event or incident/transition design, check before drafting:
Check:
variable_operationalization.md. The variable definitions written in Methods must match the operationalization table verbatim (dictionary-first). A blinded re-classification form must quote the analytic protocol's definition verbatim — paraphrase / "common-sense extension" in the form (but not the Methods) is the documented cause of a low κ that is a *definition mismatch*, not real disagreement. Cross-check with /define-variables output before drafting.Classify:
When the study elicits expert ratings — a reader study, an annotation panel, an AI-output
evaluation — the design decisions that matter are made before data collection, and the
acceptance ceiling of a perceptual / reader AI study is fixed at design time: no quality of
execution lifts a ceiling baked into the comparator, the estimand, or the reader cohort.
For an AI-system-versus-human-expert benchmark specifically, route to /design-ai-benchmarking,
which extends this subsection with arm definition, LLM-as-judge versus human-as-judge
adjudication, and a structured export schema.
| File | Read it when | Cost if read blindly |
|---|---|---|
| references/reader_elicitation_design.md | the design has a human-rater or expert-elicitation arm — rubric axes, calibration probes, operational rigor, human-as-operator, and the six ceiling decisions | ~2,400 tokens, none of which applies to a design with no reader arm |
| references/dag_adjustment.md | confounding control needs an explicit adjustment set | — |
| references/target_trial_emulation.md | the design emulates a target trial | — |
| references/venue_accept_recipe.md | it is a clinical DL / AI-validation study and the question is which venue tier the achievable design can be accepted at, and the one design move that reaches the tier above (the design→acceptance-tier ladder + the five acceptance levers, reverse-engineered from accepted OA papers; the bridge into /find-journal) | ~1,800 tokens; skip for a design with no publication-tier decision |
| references/combine_models_ablation_design.md | the model is built by combining / adapting / fine-tuning existing models (nnU-Net, TotalSegmentator, SAM/MedSAM, a pretrained backbone) — how to design the comparator as an ablation that proves the combination earns its complexity (beat the un-adapted base + the best single component + direct-train), reverse-engineered from accepted OA papers | ~1,600 tokens; skip if the model is trained de novo with no reused component |
| references/multi_model_comparison_design.md | the study's contribution is comparing several models / architectures head-to-head (CNN vs Transformer vs foundation backbone; N segmentation networks) — how to make the comparison fair: one frozen split + one preprocessing through every model, a strong self-configuring baseline (nnU-Net) not a hobbled one, matched training/HPO/compute budget (the #1 threat — "new≠better, just tuned harder") or disclosed, variance-over-single-run, a pre-specified primary metric + a paired delta test, honest ranking. Reverse-engineered from accepted OA papers | ~1,700 tokens; skip for a single-model study (use combine_models_ablation_design.md for an ablation of one model, /design-ai-benchmarking for AI-vs-human) |
| references/segmentation_failure_characterization_design.md | the claim is that a segmentation model is clinically usable, not that it scores well — a pre-specified failure taxonomy (boundary drift / missed / hallucinated / catastrophic), an acceptability endpoint with a stated scale, named judges and an adjudication rule, the tail (per-case distribution, worst percentile, catastrophic count) beside the mean, edit effort paired against manual-from-scratch and disaggregated per structure and site, and failures stratified by what predicts them. Reverse-engineered from accepted OA papers | ~1,700 tokens; skip when the endpoint is benchmark accuracy with no usability claim (metric choice → /model-evaluation; abstention / risk–coverage → /uncertainty-imaging) |
Ask whether the comparator and endpoint support the stated claim:
engineering, or a multi-agent wrapper improves extraction/classification, pre-specify a same-backbone
zero-shot or few-shot comparator on the identical input, output schema, and test split. A comparison
only against a weaker or unrelated baseline cannot establish that the proposed adaptation adds value. For an imaging model built by combining / adapting / fine-tuning existing models (nnU-Net, a foundation model, a pretrained backbone), design the full ablation ladder — un-adapted base, best single component, direct-train vs transfer — per references/combine_models_ablation_design.md. When the contribution is instead a head-to-head comparison of several models (which architecture wins), the decisive design question is comparison *fairness* — one frozen split/preprocessing through every model, a strong fairly-tuned baseline, a matched (or disclosed) compute budget, and a paired delta test — per references/multi_model_comparison_design.md. When the claim is not that a segmentation model *scores* well but that it is clinically usable, the design must carry a pre-specified failure taxonomy, an acceptability endpoint with a named judge and adjudication rule, the tail beside the mean, and edit effort paired against manual-from-scratch — per references/segmentation_failure_characterization_design.md; a mean DSC cannot be converted into a usability claim after the fact.
/self-review §D + check_scope_coherence.py flag CROSS_SECTIONAL_PROGNOSTIC / SURROGATE_CARE_DIRECTIVE against the conclusion.Recommend one primary guideline:
TRIPOD-AICLAIMSTARDSTROBEPRISMACAREARRIVEreferences/target_trial_emulation.md.scripts/adjustment_set_helper.py (flags mediator / collider / descendant adjustment and omitted confounders, and proposes a candidate backdoor set), then derive the minimal sufficient set with dagitty — see references/dag_adjustment.md. At review time /self-review Phase 2.5e + the O1–O12 probes in observational_confounding.md check this against Table 1 (including O7 over-adjustment, O10 overlapping-subset-gradient discipline, for complex-survey data O11 design-based weighting and O12 data-driven-threshold mining, O13 — a cross-sectional mediation claim cannot order X→M→Y, and O14 — a synergy/joint-effect claim needs the additive interaction scale (RERI/AP/S), not a multiplicative-only test).Whenever possible, recommend the smallest feasible repair first:
Escalate to redesign only when the central claim is not defensible otherwise.
analyze-stats when the design is basically sound but analysis details need refinementcheck-reporting after the design is lockedself-review when the user wants a pre-submission quality check on their own manuscriptwrite-paper only after the main validity risks are documented/search-lit with confirmed DOI or PMID. Mark unverified references as [UNVERIFIED - NEEDS MANUAL CHECK].[VERIFY] and ask the user.Take aperivue/design-study from the repository into ~/.claude/skills for personal
use, or into .claude/skills inside a project.
The agent identifies a skill by the name field in its header. Two skills with the
same name cannot sit side by side — one of them will be ignored.