medsci-skills 4.1.0

package/skills/define-variables/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: define-variables
+description: >
+  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 reviewer rejection. Bridges
+  /search-lit output into /write-protocol Methods.
+triggers: variable definition, phenotype definition, operationalization, cutoff justification, inclusion criteria, case definition, grouping criteria, literature-grounded definition, canonical definition, 변수 정의, 정의 근거
+tools: Read, Write, Edit, Bash, Grep, Glob
+model: inherit
+---
+
+# 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.

package/skills/define-variables/references/common_definitions.md

@@ -0,0 +1,190 @@
+# 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})`.

package/skills/define-variables/skill.yml

@@ -0,0 +1,34 @@
+schema_version: 2
+name: define-variables
+layer: C
+owner_domain: variable_operationalization
+
+when_to_use: "Turn a data dictionary + research question into a citation-backed table of exposure/outcome/covariate definitions, cutoffs, and DB variable mappings."
+when_NOT_to_use: "Drafting Methods prose (use write-protocol/write-paper); finding literature (use search-lit)."
+
+inputs:
+  - "data dictionary"
+  - "research question"
+  - "candidate literature"
+outputs:
+  - "variable operationalization table (definitions, cutoffs, DB mappings)"
+side_effects:
+  - writes_project_artifacts
+downstream_consumers:
+  - write-protocol
+  - analyze-stats
+forbidden_actions:
+  - define_phenotype_without_dictionary_citation
+  - invent_cutoff_without_literature_source
+
+# v2.1 quality card
+purpose: "Produce a literature-grounded, dictionary-cited operationalization table that prevents ad-hoc phenotype definitions."
+safety_boundaries:
+  - "Every DB variable interpretation quotes the data dictionary verbatim (dictionary-first)."
+  - "Cutoffs cite a canonical literature source; unsupported definitions are flagged, not invented."
+known_limitations:
+  - "Quality depends on a complete data dictionary; silent dictionary gaps block definitions."
+  - "No standalone demo; output is reviewed against the dictionary and sources."
+validation_commands:
+  - "cross-check each row's dictionary citation against the source dictionary"
+evidence_surface: manual_workflow

package/skills/define-variables/templates/variable_operationalization.md

@@ -0,0 +1,64 @@
+# 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
+
+| # | Variable | Role | Dict. sheet & row | Dict. verbatim | Canonical source | Definition | Cutoff | DB vars | Implementation | Ad-hoc? |
+|---|----------|------|-------------------|----------------|------------------|------------|--------|---------|----------------|---------|
+| 1 | {{var}} | exposure | `{{sheet}} r{{N}}` | `{{code→meaning verbatim from dictionary}}` | @bibkey | verbatim from guideline | value + units | `col_a, col_b` | `col_a>=X & col_b==Y` | no |
+| 2 | {{var}} | outcome | `{{sheet}} r{{N}}` | `{{verbatim}}` | @bibkey | ... | ... | ... | ... | no |
+| 3 | {{var}} | covariate | `{{sheet}} r{{N}}` | `{{verbatim}}` | @bibkey | ... | ... | ... | ... | yes |
+| 4 | {{var}} | eligibility | `{{sheet}} r{{N}}` | `{{verbatim}}` | @bibkey | ... | ... | ... | ... | no |
+
+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:
+
+| Protocol variable | DB status | Decision |
+|-------------------|-----------|----------|
+| {{name}} | not available | proxy with `...` / request from DB owner / drop |
+
+## References
+
+```bibtex
+@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

package/skills/deidentify/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: deidentify
+description: >
+  De-identify clinical research data before LLM-assisted analysis. Standalone Python CLI
+  detects PHI via regex + heuristics with 10 country locale packs (kr, us, jp, cn, de, uk,
+  fr, ca, au, in). Interactive terminal review. No LLM touches raw data — the script runs
+  locally without any network or AI calls.
+triggers: deidentify, de-identify, anonymize, 비식별화, 익명화, remove PHI, remove PII, strip patient info
+tools: Read, Bash, Glob
+model: inherit
+---
+
+# De-identification Skill
+
+You are guiding a medical researcher through data de-identification. The actual
+de-identification is performed by a **standalone Python script** that runs WITHOUT
+any LLM. Your role is to explain, guide, and verify — not to see or process raw
+PHI data.
+
+## Critical Safety Rules
+
+1. **NEVER ask the user to paste, show, or upload raw data containing PHI.**
+   The script processes data locally. You never need to see patient-level data.
+2. **NEVER read or display the mapping file contents.** It contains original PHI values.
+3. **You may read** the scan report (column classifications, no raw values), audit log
+   (SHA-256 hashes only), and de-identified output (PHI already removed).
+4. **Always communicate in the user's preferred language** about the process, but use
+   English for technical terms (PHI, HIPAA, Safe Harbor, etc.).
+
+## Reference Files
+
+- `${CLAUDE_SKILL_DIR}/references/hipaa_18_identifiers.md` — HIPAA Safe Harbor checklist
+- `${CLAUDE_SKILL_DIR}/references/korean_phi_patterns.md` — Korean-specific regex patterns
+- `${CLAUDE_SKILL_DIR}/references/date_shift_guide.md` — Date shifting best practices
+
+Read relevant references before advising the researcher.
+
+## Prerequisites
+
+- Python 3.10+
+- `openpyxl` (for .xlsx files): `pip install openpyxl`
+- Supported formats: CSV, TSV, Excel (.xlsx)
+
+## Five-Phase Workflow
+
+### Phase 1: Assessment
+
+Ask the researcher:
+1. What file format is the data? (CSV, Excel, etc.)
+2. What PHI do you expect in the data? (names, dates, IDs, etc.)
+3. Does your IRB require specific de-identification documentation?
+4. Do you need to re-identify later? (affects mapping file choice)
+
+Based on answers, recommend the appropriate command:
+- Full pipeline (most common): `python deidentify.py full <file> --locale <code>`
+- Step-by-step (cautious): `python deidentify.py scan <file> --locale <code>` first
+
+Available locale codes: `kr` (Korea), `us` (USA), `jp` (Japan), `cn` (China), `de` (Germany),
+`uk` (United Kingdom), `fr` (France), `ca` (Canada), `au` (Australia), `in` (India).
+If `--locale` is omitted, the script shows an interactive country selection menu.
+Users can provide a custom locale file via `--locale-file custom.json`.
+
+### Phase 2: Script Execution
+
+Guide the researcher to run the script. The script is located at:
+```
+${CLAUDE_SKILL_DIR}/deidentify.py
+```
+
+**Full pipeline** (recommended for most users):
+```bash
+python ${CLAUDE_SKILL_DIR}/deidentify.py full data.xlsx \
+    --locale kr \
+    --output-dir ./deidentified/ \
+    --auto-accept-safe
+```
+
+**Step-by-step** (for careful review):
+```bash
+# Step 1: Scan
+python ${CLAUDE_SKILL_DIR}/deidentify.py scan data.xlsx --locale kr --output-dir ./deidentified/
+
+# Step 2: Review (interactive)
+python ${CLAUDE_SKILL_DIR}/deidentify.py review ./deidentified/scan_report.json
+
+# Step 3: Apply
+python ${CLAUDE_SKILL_DIR}/deidentify.py apply ./deidentified/reviewed_report.json
+```
+
+**Options:**
+- `--locale CODE`: Country locale for PHI patterns (kr, us, jp, cn, de, uk, fr, ca, au, in)
+- `--locale-file PATH`: Custom locale JSON file (copy `locales/_template.json` to create one)
+- `--auto-accept-safe`: Skip confirmation for columns classified as SAFE (faster for large datasets)
+- `--hash-mapping`: Store SHA-256 hashes instead of original values in mapping file (one-way, more secure)
+- `--output-dir`: Where to save de-identified file, mapping, and audit log
+- `-v/--verbose`: Enable debug logging
+
+### Phase 3: Interactive Review Guidance
+
+The script's terminal review has three passes:
+
+1. **Pass 1 — Column Classification**: Each column is shown as PHI / REVIEW_NEEDED / SAFE.
+   The researcher confirms or overrides each classification.
+2. **Pass 2 — Undecided Items**: Columns that weren't resolved in Pass 1 get a second look
+   with more sample values displayed.
+3. **Pass 3 — Final Summary**: A table of all planned actions. The researcher can edit
+   individual decisions before confirming.
+
+Coach the researcher. Deliver these prompts in the researcher's preferred language:
+- "Columns classified as PHI are anonymized by default. Press 'k' to keep the original value."
+- "REVIEW_NEEDED are columns the script could not classify. Check the sample values and decide."
+- "SAFE means no PHI detected. Press 'r' to request re-review if any column looks suspicious."
+
+### Phase 4: Verify and Document
+
+After the script completes, help the researcher verify:
+
+1. **Read the audit log** (safe — contains only hashes):
+   ```bash
+   cat ./deidentified/audit_log.csv | head -20
+   ```
+   Verify the number of changes, affected columns, and PHI types.
+
+2. **Spot-check the de-identified file** (safe — PHI already removed):
+   Read a few rows to confirm pseudonyms (P0001, etc.), date shifts, and [REDACTED] markers
+   appear where expected.
+
+3. **Check that sensitive columns are actually removed**:
+   Verify no original names, phone numbers, or RRN values remain.
+
+4. **Mapping file security**:
+   - Remind the researcher: "mapping.json contains original patient identifiers — treat it as restricted."
+   - Recommend storing it separately from the de-identified data
+   - File permissions are automatically set to 0600 (owner-only)
+
+### Phase 5: Documentation
+
+Generate a de-identification methods paragraph for the manuscript or IRB:
+
+Template:
+> Protected health information was removed from the dataset prior to analysis using
+> a rule-based de-identification tool (deidentify.py, medsci-skills) with the [COUNTRY]
+> locale pattern pack. The tool scanned column names and cell values using regex patterns
+> for country-specific identifiers (e.g., national ID numbers, phone numbers), email
+> addresses, dates, and addresses. Each column classification was reviewed by the
+> researcher in an interactive terminal session. Names were replaced with pseudonyms
+> (P0001, P0002, ...), dates were shifted by a random per-patient offset (±365 days)
+> preserving relative temporal intervals, and direct identifiers (phone numbers, email
+> addresses, national ID numbers) were suppressed. A total of [N] cells across [M]
+> columns were de-identified. The de-identification mapping file was stored separately
+> under restricted access (file permissions 0600).
+
+Customize based on the actual audit log statistics.
+
+## Cross-Skill Integration
+
+- **deidentify** sits BEFORE `clean-data` in the research pipeline
+- After de-identification, hand off to `/clean-data` for data quality profiling
+- `/analyze-stats` can safely process the de-identified output
+- `/write-paper` Methods section should reference the de-identification process
+- `/write-protocol` can use the HIPAA/PIPA reference files for protocol documentation
+
+## Output Files
+
+| File | Contains PHI? | Safe for Claude? | Purpose |
+|------|:------------:|:----------------:|---------|
+| `*_deidentified.xlsx/csv` | No | Yes | De-identified data for analysis |
+| `mapping.json` | **YES** | **No** | Original ↔ pseudonym mapping |
+| `audit_log.csv` | No (hashes only) | Yes | What was changed and where |
+| `scan_report.json` | No | Yes | Column classification results |
+| `reviewed_report.json` | No | Yes | Researcher-reviewed classifications |
+
+## Scope and Limitations
+
+**Supported (v1)**:
+- Structured tabular data: CSV, TSV, Excel (.xlsx)
+- 10 country locales with country-specific PHI patterns:
+  - Korea (kr): RRN (주민번호), phone, email, address, Hangul names, dates
+  - USA (us): SSN, US phone, US address, zip codes
+  - Japan (jp): マイナンバー, Japanese phone, 都道府県 address, Kanji names
+  - China (cn): 身份证号, Chinese phone, 省市区 address, Chinese names
+  - Germany (de): Steuer-ID, German phone, Straße address
+  - UK (uk): NHS Number, NI Number, UK phone, postcodes
+  - France (fr): NIR/INSEE, French phone, Rue address
+  - Canada (ca): SIN, Canadian phone, postal codes
+  - Australia (au): TFN, Medicare number, AU phone
+  - India (in): Aadhaar, PAN, Indian phone, pin codes
+- Universal patterns (all locales): email, ISO dates, high-cardinality numeric IDs (MRN)
+- English column names recognized across all locales
+- Custom locale support via `--locale-file` with template
+- Pseudonymization, date shifting, ID replacement, suppression
+
+**NOT supported (planned for v2)**:
+- DICOM image metadata (PS3.15 Annex E) — requires pydicom
+- Clinical free-text NER (clinical notes, radiology reports)
+- Automated k-anonymity / l-diversity assessment
+- SPSS (.sav), SAS (.sas7bdat), or other statistical formats
+
+## Anti-Hallucination
+
+- **Never fabricate file paths, URLs, DOIs, or package names.** Verify existence before recommending.
+- **Never invent journal metadata, impact factors, or submission policies** without verification at the journal's website.
+- If a tool, package, or resource does not exist or you are unsure, say so explicitly rather than guessing.