Define Variables

Define-Variables Skill

Map each exposure, outcome, covariate, and eligibility variable to a canonical guideline/consensus definition, cross-check it against prior operationalizations in comparable cohorts, then map it to the available DB variables. Call after /design-study (and /search-lit), before /write-protocol.

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 the 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 most common observational-study error: assuming a column code (status == 0, grade == 4) means what it intuitively reads like, when the codebook says otherwise.

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.

Recommend committing a DICTIONARY_FIRST_POLICY.md at the project root (or shared-config path) with the canonical dictionary path and the escalation contact.

Exit gate: before Tier 1, cross-check every row's Dict. sheet & row and Dict. verbatim against the source dictionary; no DB-backed row may be left blank.

Tier 1 — Canonical index lookup (no API calls)

Look the variable up in references/common_definitions.md (hepatology, metabolic/endocrine, renal, pulmonary, cardiovascular, oncology/imaging incidentalomas, alcohol exposure). On a hit, record the guideline, year, canonical cutoff, and 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 — never a general sweep, which buries the signal. Query pattern:

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

Stop searching a variable once the first 1-2 papers converge on the same definition. If more than five variables need Tier 2, list them and confirm with the user before running the rest.

Tier 3 — Verification

Every definition, cutoff, and era anchor must come from a verified source — a clinical guideline, a peer-reviewed paper with DOI, or an established registry data dictionary. Never take a phenotype threshold from the model's prior or a reference from memory. Before finalizing, run /verify-refs on the accumulated BibTeX to confirm every citation exists in PubMed/CrossRef. A choice with no canonical source is flagged Ad-hoc: yes, justified in 1-2 sentences, and confirmed by the user before it propagates into /write-protocol or /analyze-stats.