define-variables

Name: define-variables
Author: Aperivue

208stars53forks

How to install define-variables?

aperivue/medsci-skills/define-variables

$npx -y skills add Aperivue/medsci-skills --skill define-variables

Installs into the current project.

Summary

Literature-grounded variable operationalization for observational research. Turns a data dictionary + research question into a citation-backed table of exposure/outcome/covariate definitions, cutoffs, and DB variable mappings. Prevents ad-hoc phenotype definitions that invite rev

Files · 1

View on GitHub

SKILL.md

1	# Define-Variables Skill
2
3	## Purpose
4
5	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.
6
7	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.
8
9	Use it when:
10	- a study question is known and variables are being selected
11	- inclusion/exclusion criteria or phenotype definitions need citation backing
12	- a data dictionary has ambiguous or derived variables (eGFR formula, BMI class, liver steatosis criteria, etc.)
13	- a reviewer asked "why this cutoff?"
14	- a retrospective audit reveals drifted definitions across projects in the same cohort
15
16	Call after `/design-study`, before `/write-protocol`.
17
18	## Communication Rules
19
20	- Communicate in the user's preferred language.
21	- All variable names, guideline names, cutoffs in English.
22	- Produce one artifact: `variable_operationalization.md` in the project root (or path the user specifies).
23
24	## Inputs
25
26	1. Research question (one sentence)
27	2. Candidate variables — exposure, outcome, key covariates, eligibility filters
28	3. Data dictionary path (xlsx / csv / markdown) OR explicit list of available DB columns
29	4. Cohort type (e.g., health-screening, NHANES-like, claims, registry) — informs which prior-art cohort to compare against
30
31	Missing inputs → ask once, then proceed.
32
33	## 4-Tier Pipeline (DB codebook + token-efficient literature)
34
35	### Tier 0 — DB codebook lookup (mandatory for DB-backed observational studies)
36
37	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.
38
39	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.
40
41	Concrete procedure per variable:
42
43	1. Locate the variable in the dictionary by exact column name.
44	2. Copy verbatim: the sheet title, row number, and full code→meaning mapping (or unit/range statement for continuous vars).
45	3. Paste into the `Dict. sheet & row` + `Dict. verbatim` columns of the operationalization table.
46	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.
47
48	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.
49
50	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`.
51
52	Exit gate: `check_dictionary_citations.py` (or equivalent) PASS on the operationalization table before running Tier 1.
53
54	### Tier 1 — Canonical index lookup (no API calls)
55
56	Check `references/common_definitions.md` (shipped with skill) for the variable. Covers high-frequency constructs:
57
58	- Liver: MASLD (AASLD 2023), MetALD (AASLD 2023), MAFLD (2020), NAFLD (legacy), ALD, viral hepatitis (AASLD 2022/2024 HBV, AASLD-IDSA HCV)
59	- 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)
60	- Renal: CKD (KDIGO 2024), eGFR formulas (CKD-EPI 2021 race-free, MDRD legacy), incidental renal mass (ACR 2018 white paper, Bosniak 2019)
61	- Pulmonary: COPD (GOLD 2024), emphysema imaging (Fleischner 2015)
62	- CV: CAC scoring

People who liked this also viewed

6 picks

Type

define-variables

208stars53forks

View on GitHub

How to install define-variables?

aperivue/medsci-skills/define-variables

$npx -y skills add Aperivue/medsci-skills --skill define-variables

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Define-Variables Skill
2
3	## Purpose
4
5	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.
6
7	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.
8
9	Use it when:
10	- a study question is known and variables are being selected
11	- inclusion/exclusion criteria or phenotype definitions need citation backing
12	- a data dictionary has ambiguous or derived variables (eGFR formula, BMI class, liver steatosis criteria, etc.)
13	- a reviewer asked "why this cutoff?"
14	- a retrospective audit reveals drifted definitions across projects in the same cohort
15
16	Call after `/design-study`, before `/write-protocol`.
17
18	## Communication Rules
19
20	- Communicate in the user's preferred language.
21	- All variable names, guideline names, cutoffs in English.
22	- Produce one artifact: `variable_operationalization.md` in the project root (or path the user specifies).
23
24	## Inputs
25
26	1. Research question (one sentence)
27	2. Candidate variables — exposure, outcome, key covariates, eligibility filters
28	3. Data dictionary path (xlsx / csv / markdown) OR explicit list of available DB columns
29	4. Cohort type (e.g., health-screening, NHANES-like, claims, registry) — informs which prior-art cohort to compare against
30
31	Missing inputs → ask once, then proceed.
32
33	## 4-Tier Pipeline (DB codebook + token-efficient literature)
34
35	### Tier 0 — DB codebook lookup (mandatory for DB-backed observational studies)
36
37	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.
38
39	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.
40
41	Concrete procedure per variable:
42
43	1. Locate the variable in the dictionary by exact column name.
44	2. Copy verbatim: the sheet title, row number, and full code→meaning mapping (or unit/range statement for continuous vars).
45	3. Paste into the `Dict. sheet & row` + `Dict. verbatim` columns of the operationalization table.
46	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.
47
48	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.
49
50	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`.
51
52	Exit gate: `check_dictionary_citations.py` (or equivalent) PASS on the operationalization table before running Tier 1.
53
54	### Tier 1 — Canonical index lookup (no API calls)
55
56	Check `references/common_definitions.md` (shipped with skill) for the variable. Covers high-frequency constructs:
57
58	- Liver: MASLD (AASLD 2023), MetALD (AASLD 2023), MAFLD (2020), NAFLD (legacy), ALD, viral hepatitis (AASLD 2022/2024 HBV, AASLD-IDSA HCV)
59	- 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)
60	- Renal: CKD (KDIGO 2024), eGFR formulas (CKD-EPI 2021 race-free, MDRD legacy), incidental renal mass (ACR 2018 white paper, Bosniak 2019)
61	- Pulmonary: COPD (GOLD 2024), emphysema imaging (Fleischner 2015)
62	- CV: CAC scoring

People who liked this also viewed

6 picks

Type