Define Variables

Define-Variables Skill

Purpose

Every observational study operationalizes abstract constructs (MASLD, CKD, emphysema, obesity, incidentaloma) into concrete rules against the available data dictionary. When that operationalization is invented ad-hoc from the dictionary alone, reviewers reject on construct validity regardless of downstream statistics.

This skill forces a literature-first pass: each variable is mapped to a canonical guideline/consensus definition, cross-checked against prior operationalizations in comparable cohorts, then mapped to available DB variables. Ad-hoc deviations are flagged explicitly and justified, not hidden.

Use it when:

• a study question is known and variables are being selected
• inclusion/exclusion criteria or phenotype definitions need citation backing
• a data dictionary has ambiguous or derived variables (eGFR formula, BMI class, liver steatosis criteria, etc.)
• a reviewer asked "why this cutoff?"
• a retrospective audit reveals drifted definitions across projects in the same cohort

Call after /design-study, before /write-protocol.

Communication Rules

• Communicate in the user's preferred language.
• All variable names, guideline names, cutoffs in English.
• Produce one artifact: variable_operationalization.md in the project root (or path the user specifies).

Inputs

1. Research question (one sentence) 2. Candidate variables — exposure, outcome, key covariates, eligibility filters 3. Data dictionary path (xlsx / csv / markdown) OR explicit list of available DB columns 4. Cohort type (e.g., health-screening, NHANES-like, claims, registry) — informs which prior-art cohort to compare against

Missing inputs → ask once, then proceed.

4-Tier Pipeline (DB codebook + token-efficient literature)

Tier 0 — DB codebook lookup (mandatory for DB-backed observational studies)

Trigger: project has a project.yaml::db.dictionary_path field pointing to a machine-readable codebook (xlsx/csv/markdown), OR user supplied a dictionary path in inputs. If neither, skip to Tier 1.

For every candidate DB variable — before touching literature — open the dictionary and record, verbatim, the sheet name, row number, and code→meaning mapping. This prevents the single most common observational-study error: assuming a column code (status == 0, grade == 4) means what it intuitively reads like, when the codebook says otherwise.

Concrete procedure per variable:

1. Locate the variable in the dictionary by exact column name. 2. Copy verbatim: the sheet title, row number, and full code→meaning mapping (or unit/range statement for continuous vars). 3. Paste into the Dict. sheet & row + Dict. verbatim columns of the operationalization table. 4. If the variable is not found, OR the codebook is silent on a specific code value, file a question to the DB owner / data steward. Do NOT infer from cross-tabs, do NOT guess, do NOT proceed with that variable until a verbatim answer exists.

Empirical checks (value distributions, cross-tabs with related columns) are useful for sanity testing after the verbatim codebook meaning is recorded — never as a substitute for it.

Project-level binding (recommended): commit a DICTIONARY_FIRST_POLICY.md at the project root (or shared-config path) capturing the canonical dictionary path + escalation contact. Cross-project rule template: ~/.claude/rules/dictionary-first.md.

Exit gate: check_dictionary_citations.py (or equivalent) PASS on the operationalization table before running Tier 1.

Tier 1 — Canonical index lookup (no API calls)

Check references/common_definitions.md (shipped with skill) for the variable. Covers high-frequency constructs:

• Liver: MASLD (AASLD 2023), MetALD (AASLD 2023), MAFLD (2020), NAFLD (legacy), ALD, viral hepatitis (AASLD 2022/2024 HBV, AASLD-IDSA HCV)
• Metabolic: T2DM (ADA 2024), prediabetes (ADA 2024), metabolic syndrome (IDF 2009 / NCEP ATP III / K-NCEP), obesity/BMI (WHO Asian 2004 + WHO global), HTN (ACC/AHA 2017 + JNC-8), dyslipidemia (NCEP ATP III, 2023 AHA/ACC)
• Renal: CKD (KDIGO 2024), eGFR formulas (CKD-EPI 2021 race-free, MDRD legacy), incidental renal mass (ACR 2018 white paper, Bosniak 2019)
• Pulmonary: COPD (GOLD 2024), emphysema imaging (Fleischner 2015)
• CV: CAC scoring (Agatston 1990, MESA percentiles), CAD risk (2018 ACC/AHA cholesterol, PREVENT 2023)
• Cancer: gastric cancer H. pylori (Maastricht VI 2022), thyroid nodule (ACR TI-RADS 2017), gallbladder polyp (European 2022 joint guideline)
• Imaging incidentalomas: adrenal (ACR 2023), pancreas (ACR 2017), renal (ACR 2018), thyroid (ACR 2017)

If the variable hits Tier 1, record: guideline, year, canonical cutoff, BibTeX key. Done — no /search-lit call.

Tier 2 — Targeted /search-lit (focused queries only)

For variables NOT in Tier 1, OR when subgroup justification is needed (Asian-specific cutoff, pediatric, young-adult, pregnancy, etc.), call /search-lit with one query per variable — not a general sweep. Query pattern:

"{construct} definition {cohort type} {subgroup qualifier}"
e.g., "obstructive sleep apnea prevalence Korean health screening cohort"

Cap: 5 queries per session. Stop early if first 1-2 papers converge on the same definition.

Tier 3 — Verification

Before finalizing, run /verify-refs on the accumulated BibTeX to confirm every citation exists in PubMed/CrossRef. Ad-hoc choices (no canonical source found) must be flagged Ad-hoc: yes and justified with 1-2 sentences — never hidden.

Output Template

Write to {project_root}/variable_operationalization.md using templates/variable_operationalization.md. Required structure:

1. Header: research question, cohort type, date, author 2. Operationalization table — one row per variable:

| Variable | Role | Dict. sheet & row | Dict. verbatim | Canonical source | Definition | Cutoff | DB vars | Implementation | Ad-hoc? |

• Role: exposure / outcome / covariate / eligibility
• Dict. sheet & row: e.g. 5-1.복부초음파 r12 — mandatory if a DB dictionary exists
• Dict. verbatim: full code→meaning string copied from the dictionary — mandatory same condition
• Canonical source: BibTeX key (e.g., @rinella2023_aasld_masld)
• Definition: one line, verbatim from guideline where possible
• Cutoff: numeric + units
• DB vars: exact dictionary column names used
• Implementation: SQL/pandas-style pseudocode (e.g., bmi>=25 & (b_tg>=150 | b_hdl<40))
• Ad-hoc?: yes/no. If yes, justification below table

3. Ad-hoc justifications — for each yes row 4. Mapping gaps — variables in the protocol with no DB equivalent; list proxy / omit / request decisions 5. References — BibTeX block

Non-Goals

• Statistical analysis → /analyze-stats
• Manuscript drafting → /write-paper
• Data cleaning / missingness → /clean-data
• Sample size → /calc-sample-size

Pipeline Position

intake-project → design-study → search-lit → define-variables → write-protocol → analyze-stats → write-paper
                                              ^^^^^^^^^^^^^^^

/orchestrate should insert this skill between /search-lit and /write-protocol for any observational cohort or registry study.

Anti-Hallucination

Every variable definition, cutoff, and era anchor must be grounded in a verified source — a clinical guideline, a peer-reviewed paper with DOI, or an established registry data dictionary. Never invent a phenotype threshold from the model's prior; if the source is unknown, mark the row Ad-hoc: yes and require user confirmation before it propagates into /write-protocol or /analyze-stats. When citing papers to justify a cutoff, verify the citation via /search-lit or /verify-refs — do not carry references from memory alone. The output table must carry explicit source, year, and guideline_version columns so downstream skills can re-verify.

Failure Modes to Avoid

0. Ad-hoc DB code interpretation (the single most costly observational-study error). Interpreting a column value (status == 0, grade == 4) by its surface reading without consulting the codebook. Tier 0 exists specifically to prevent this. Distinguish from Failure #1: Tier 0 says "once you've picked the DB column, quote the codebook verbatim before using its values." Failure #1 says "don't pick DB columns before picking definitions from literature." Both rules co-exist. 1. Dictionary-first framing — starting from what columns exist, then picking a definition that matches. Always flip: definition first, then map. 2. Cutoff drift — using a different cutoff than the cited guideline without justification (e.g., BMI≥23 cited as WHO Asian while text says ≥25). 3. Mixing eras — 2020 MAFLD criteria with 2023 MASLD criteria in the same analysis. Pick one and note why. 4. Silent ad-hoc — introducing a novel cutoff without the Ad-hoc: yes flag. 5. Sweep-style /search-lit — running a generic lit search instead of one focused query per gap variable. Wastes tokens and buries the signal. 6. Dose/duration structural-missingness — operationalizing a dose/duration covariate (pack-years, cessation-years, alcohol grams/week) anchored to a categorical exposure (smoking status, alcohol use) without specifying what the reference level (never-smoker, never-drinker) does to the dose. A never-smoker's pack-years is a structural zero, not a missing value; conflating the two collapses the analytic sample under complete-case modeling and lets MICE fabricate a non-zero dose for the unexposed. Operationalize it explicitly — add a row with Role = covariate and Implementation = "IF status == 'never' THEN dose = 0 ELSE measured_value" — and adjust on the categorical status variable, reserving the continuous dose for an exposed-only secondary analysis. /clean-data (categorical-implied-zero flag) and /analyze-stats ("Covariate Pitfalls") enforce this downstream.

Canonical Definitions Index (Tier 1)

Curated index of high-frequency phenotype/variable definitions for observational research. Each entry gives the authoritative source, year, cutoff, BibTeX key stub, and DOI. Always quote the cutoff verbatim — do not paraphrase.

Update cadence: review annually or when a major guideline revision drops.

---

Hepatology

MASLD (Metabolic dysfunction-associated Steatotic Liver Disease)

• Source: Rinella et al., AASLD multi-society Delphi consensus, Hepatology 2023
• Definition: Hepatic steatosis (imaging/histology) + ≥1 cardiometabolic risk factor, no other identifiable cause
• Cardiometabolic criteria (≥1 of 5):
• BMI ≥25 kg/m² (≥23 for Asian populations) OR WC >94 cm (M) / >80 cm (F)
• FPG ≥100 mg/dL OR 2h-PG ≥140 OR HbA1c ≥5.7% OR T2DM OR T2DM treatment
• BP ≥130/85 OR antihypertensive treatment
• TG ≥150 mg/dL OR lipid-lowering treatment
• HDL ≤40 (M) / ≤50 (F) mg/dL OR lipid-lowering treatment
• BibTeX: @rinella2023_aasld_masld
• DOI: 10.1097/HEP.0000000000000520

MetALD

• Source: Same AASLD 2023 consensus
• Definition: MASLD criteria + moderate alcohol (M 140–350 g/wk, F 70–210 g/wk)
• BibTeX: @rinella2023_aasld_masld

ALD (Alcohol-associated Liver Disease)

• Source: AASLD 2023 consensus + Crabb et al., AASLD practice guidance 2020
• Definition: Steatosis + alcohol >350 g/wk (M) / >210 g/wk (F)
• BibTeX: @crabb2020_aasld_ald, @rinella2023_aasld_masld

MAFLD (legacy, 2020)

• Source: Eslam et al., international expert consensus, J Hepatol 2020
• BibTeX: @eslam2020_mafld
• Note: Superseded by MASLD (2023) — use only for backwards comparability.

HBV chronic infection

• Source: Terrault et al., AASLD 2022/2018 guidance
• Definition: HBsAg positive ≥6 months
• BibTeX: @terrault2018_aasld_hbv

HCV chronic infection

• Source: AASLD-IDSA HCV guidance (latest rolling update at hcvguidelines.org)
• Definition: Anti-HCV positive + HCV RNA detectable
• BibTeX: @aasld_idsa_hcv_guidance

Liver fibrosis non-invasive scores

• FIB-4: Sterling et al. 2006. Cutoffs <1.3 exclude advanced fibrosis (<65 y); <2.0 (≥65 y). >2.67 rule-in. @sterling2006_fib4
• NFS (NAFLD fibrosis score): Angulo et al. 2007. @angulo2007_nfs

---

Metabolic / Endocrine

Type 2 Diabetes

• Source: ADA Standards of Care in Diabetes — 2024, Diabetes Care
• Definition (any ONE):
• FPG ≥126 mg/dL
• 2h-PG ≥200 mg/dL on 75g OGTT
• HbA1c ≥6.5%
• Classic hyperglycemia symptoms + random PG ≥200
• Physician diagnosis OR antidiabetic medication
• BibTeX: @ada2024_standards
• DOI: 10.2337/dc24-S002

Prediabetes

• Source: ADA 2024
• Definition: FPG 100–125 OR 2h-PG 140–199 OR HbA1c 5.7–6.4%

Metabolic Syndrome

• Source: IDF 2009 harmonized (Alberti et al., Circulation) — ≥3 of 5 criteria
• Criteria:
• WC (ethnicity-specific: Asian M ≥90, F ≥80 cm)
• TG ≥150 OR treatment
• HDL <40 (M) / <50 (F) OR treatment
• BP ≥130/85 OR antihypertensive treatment
• FPG ≥100 OR T2DM treatment
• BibTeX: @alberti2009_idf_harmonized
• DOI: 10.1161/CIRCULATIONAHA.109.192644

Obesity (BMI)

• WHO global: Overweight ≥25, obese ≥30 kg/m². @who2000_obesity
• *WHO Asian (2004, Lancet)*: Overweight ≥23, obese ≥25. @who2004_asian_bmi
• Korean Society for the Study of Obesity (KSSO) 2022: Same 23/25 thresholds. @ksso2022_obesity

Hypertension

• ACC/AHA 2017: ≥130/80 = stage 1. @whelton2017_accaha_htn
• JNC-8 / ESC (legacy): ≥140/90. @james2014_jnc8
• Pick one explicitly — do not mix.

Dyslipidemia

• Source: 2018 AHA/ACC/multi-society cholesterol guideline; 2023 update
• BibTeX: @grundy2019_aha_cholesterol

---

Renal

CKD

• Source: KDIGO 2024 CKD guideline, Kidney Int
• Definition: eGFR <60 mL/min/1.73m² OR markers of kidney damage (ACR ≥30 mg/g etc.) ≥3 months
• Staging: G1–G5 by eGFR; A1–A3 by albuminuria
• BibTeX: @kdigo2024_ckd

eGFR formulas

• CKD-EPI 2021 (race-free) — NEJM 2021, Inker et al. @inker2021_ckdepi2021. Current KDIGO-recommended.
• CKD-EPI 2009 — legacy, race-based. @levey2009_ckdepi
• MDRD — obsolete for clinical use; still seen in older datasets. @levey2006_mdrd

Incidental Renal Mass

• Source: ACR White Paper 2018 (Herts et al., JACR)
• Cutoffs: <1 cm too small to characterize; ≥1 cm workup per size/attenuation; growth >5 mm/y concerning
• BibTeX: @herts2018_acr_renal
• DOI: 10.1016/j.jacr.2017.10.028

Bosniak Classification (cystic renal mass)

• Source: Silverman et al., Radiology 2019 update
• BibTeX: @silverman2019_bosniak

---

Pulmonary

COPD

• Source: GOLD 2024 Report
• Definition: Post-bronchodilator FEV1/FVC <0.70 + compatible symptoms/exposure
• Severity (GOLD 1–4) by FEV1% predicted: ≥80 / 50–79 / 30–49 / <30
• BibTeX: @gold2024

Emphysema (imaging)

• Source: Fleischner Society 2015 statement (Lynch et al., Radiology)
• CT pattern classification: centrilobular (trace/mild/moderate/confluent/advanced destructive), paraseptal, panlobular
• BibTeX: @lynch2015_fleischner_emphysema
• DOI: 10.1148/radiol.2015141579

---

Cardiovascular

CAC (Coronary Artery Calcium)

• Agatston method: Agatston et al., JACC 1990. @agatston1990
• MESA percentiles (age/sex/race): McClelland et al. 2015. @mcclelland2015_mesa
• Categories: 0 / 1–99 / 100–399 / ≥400 (widely used)

ASCVD risk

• Pooled Cohort Equations: 2013 ACC/AHA. @goff2014_pce
• PREVENT (2023): AHA new risk calculator, Khan et al., Circulation. @khan2023_prevent

---

Oncology / Imaging incidentalomas

Thyroid nodule

• ACR TI-RADS 2017: Tessler et al., JACR. @tessler2017_tirads

Gallbladder polyp

• European joint guideline 2022: Foley et al., Eur Radiol. @foley2022_gb_polyp

Adrenal incidentaloma

• ACR 2023 white paper: Mayo-Smith et al. @mayosmith2023_acr_adrenal
• ESE 2023 clinical: Fassnacht et al., Eur J Endocrinol. @fassnacht2023_ese_adrenal

Pancreatic cystic lesion

• ACR 2017 white paper: Megibow et al., JACR. @megibow2017_acr_pancreas

H. pylori / gastric

• Maastricht VI / Florence Consensus 2022: Malfertheiner et al., Gut. @malfertheiner2022_maastricht6

---

Alcohol exposure

Standard drink (Korea)

• 1 drink ≈ 10 g ethanol (KNHANES; KCDC standard-drink definition)
• ALD cutoffs above use grams/week, not drinks/week — convert when operationalizing.

AUDIT-C / AUDIT

• Bush et al. 1998; Saunders et al. 1993. @bush1998_auditc, @saunders1993_audit

---

How to extend this file

1. Add a new subsection under the appropriate organ/domain. 2. Cite the authoritative guideline/consensus (not a secondary review). 3. Quote the cutoff exactly — include units. 4. Provide BibTeX key stub + DOI. 5. If multiple competing guidelines exist (e.g., HTN 130 vs 140), list both and note "pick one explicitly." 6. Commit with message: define-variables: add {construct} canonical definition ({guideline year}).

Variable Operationalization — {{PROJECT_SHORT_TITLE}}

• Research question: {{ONE_SENTENCE_Q}}
• Cohort: {{COHORT_NAME_TYPE}} (e.g., Institutional Health Screening Cohort, retrospective)
• Author: {{AUTHOR_NAME}}
• Last updated: {{YYYY-MM-DD}}
• Upstream artifacts: design_study.md, search_lit_results.md (if present)

Operationalization table

Roles: exposure / outcome / covariate / eligibility

Dict. sheet & row / Dict. verbatim (mandatory for DB-backed projects):

• Citation format example (categorical): sheet = {{dictionary_sheet}}, row = r{{N}}, verbatim = 0={{meaning}}, 1={{meaning}}, ... (copied exactly from the codebook).
• Mandatory for observational studies that have a data dictionary (e.g., NHIS, KNHANES, UK Biobank, institutional EMR / health-screening registries) — it cannot be left blank. Record the project-level policy in DICTIONARY_FIRST_POLICY.md (or a shared config) in the repo.
• For a code value not specified in the dictionary → hold off filling that row until you have asked the DB owner / data steward and received an answer.
• Self-evident continuous variables such as BMI/SBP may be marked dict: n/a (continuous). The cutoff still requires a canonical source.

Ad-hoc justifications

For each row flagged Ad-hoc: yes, document:

{{variable_name}}

• Why no canonical source: e.g., no guideline for this subgroup; novel combination of existing criteria
• Chosen rule: precise cutoff / logic
• Sensitivity plan: alternative cutoff to test in sensitivity analysis
• Reviewer-facing justification: 1-2 sentences that will appear in Methods

Mapping gaps

Variables defined in the protocol but NOT directly available in the DB:

References

@article{rinella2023_aasld_masld,
  author  = {Rinella, Mary E and others},
  title   = {A multisociety {Delphi} consensus statement on new fatty liver disease nomenclature},
  journal = {Hepatology},
  year    = {2023},
  doi     = {10.1097/HEP.0000000000000520}
}

% add one entry per cited canonical source

Verification log

• [ ] Tier 1 lookups documented (guideline year, cutoff quoted)
• [ ] Tier 2 /search-lit queries logged (query string + papers retained)
• [ ] Tier 3 /verify-refs passed (0 unverified citations)
• [ ] No silent ad-hoc — every deviation flagged and justified