medsci-skills 4.1.0

package/skills/replicate-study/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: replicate-study
+description: Replicate an existing cohort study's methodology on a different database. Extracts study design from a source paper, maps variables to the target DB via harmonization table, generates analysis code, and produces a replication difference report.
+triggers: replicate study, replicate paper, 논문 복제, 방법론 복제, reproduce study, replication, 다른 DB로, swap database, 데이터 교체
+tools: Read, Write, Edit, Bash, Grep, Glob
+model: opus
+---
+
+# Replicate Study Skill
+
+You are assisting a medical researcher in replicating an existing published study's methodology
+on a different database. This is a common research strategy: take a validated methodology from
+Paper A (e.g., NHIS cohort study) and apply it to Database B (e.g., KNHANES, NHANES, or another
+cohort) to produce a new paper with the same analytical rigor.
+
+## When to Use
+
+- Researcher has a published paper they want to replicate on their own data
+- Swapping exposure/outcome variables within the same DB
+- Cross-national replication (e.g., Korean study → US data, or vice versa)
+- Extending a single-institution study to a national cohort
+
+## Inputs
+
+1. **Source paper**: PDF, DOI, or markdown of the paper to replicate
+2. **Target database path**: CSV/SAS data file(s) to use
+3. **Harmonization table** (optional): CSV mapping source → target variables
+   - Default: `${SKILL_DIR}/references/harmonization_knhanes_nhanes.csv` (if KNHANES↔NHANES)
+
+## Reference Files
+
+- `${SKILL_DIR}/references/methodology_extraction_template.md` — checklist for extracting study design
+- `${SKILL_DIR}/references/harmonization_knhanes_nhanes.csv` — KNHANES↔NHANES variable mapping (67 rows)
+- `${SKILL_DIR}/references/harmonization_3country.csv` — KNHANES+NHANES+CHNS 3-country mapping (45 rows, if available)
+- Upstream templates (read on demand):
+  - `medsci-skills/skills/write-paper/references/paper_types/nhis_cohort.md`
+  - `medsci-skills/skills/write-paper/references/paper_types/cross_national.md`
+  - `medsci-skills/skills/analyze-stats/references/analysis_guides/survey_weighted.md`
+  - `medsci-skills/skills/analyze-stats/references/analysis_guides/propensity_score.md`
+
+## Workflow
+
+### Phase 1: Source Paper Analysis
+
+1. Read the source paper (PDF → text, or markdown).
+2. Extract methodology using the extraction template:
+   - **Study design**: cohort / cross-sectional / case-control
+   - **Database**: name, country, years, N
+   - **Population**: inclusion/exclusion criteria, age range
+   - **Exposure**: variable name, definition, coding
+   - **Outcome**: variable name, definition, coding
+   - **Covariates**: full list with definitions
+   - **Statistical methods**: regression type, adjustment model, subgroup analyses
+   - **Survey design**: weights, strata, PSU (if applicable)
+   - **Sensitivity analyses**: list all
+3. Output: structured extraction summary for user review.
+
+### Phase 2: Variable Mapping
+
+1. Load the harmonization table (CSV with columns: domain, concept, source_var, target_var, notes).
+2. For each extracted variable (exposure, outcome, covariates):
+   - Find the matching row in the harmonization table
+   - Flag: DIRECT_MATCH / RECODE_NEEDED / NOT_AVAILABLE / PROXY_AVAILABLE
+3. Generate a **mapping report**:
+   - Green: directly available (no recoding)
+   - Yellow: available but needs recoding (document transformation)
+   - Red: not available in target DB (propose proxy or exclusion)
+4. Output: variable mapping table for user approval.
+
+### Phase 3: Code Generation
+
+1. Generate analysis code (Python with `pandas` + R via `subprocess` for survey-weighted):
+   a. **Data loading & cleaning**: read target DB, apply inclusion/exclusion
+   b. **Variable derivation**: recode variables per mapping table
+   c. **Survey design setup**: define svydesign object (strata, PSU, weights)
+   d. **Table 1**: demographics by exposure group (weighted)
+   e. **Main analysis**: replicate the primary model (logistic/Cox/linear regression)
+   f. **Subgroup analyses**: if specified in source paper
+   g. **Sensitivity analyses**: replicate all listed in source paper
+2. Use `/analyze-stats` templates where available (survey_weighted, propensity_score).
+3. All code must be self-contained and reproducible.
+
+### Phase 4: Difference Report
+
+Generate a structured difference report documenting:
+
+| Section | Content |
+|---------|---------|
+| Study Design | Same / Modified (explain) |
+| Database | Source DB → Target DB (N, years, country) |
+| Population | Inclusion/exclusion differences |
+| Variable Mapping | Full mapping table with match status |
+| Unavailable Variables | What's missing and how handled |
+| Methodological Differences | Any forced changes (e.g., BMI cutoffs, LDL calculation) |
+| Expected Differences | Why results may differ (population, measurement, cultural) |
+
+Save as `replication_report.md` in the working directory.
+
+### Phase 5: Validation Checklist
+
+Before reporting completion, verify:
+
+- [ ] All source paper covariates accounted for (mapped, proxied, or documented as missing)
+- [ ] Survey weights correctly applied (NEVER analyze unweighted if source used weights)
+- [ ] Obesity/BMI cutoffs match target population standards (Asian vs WHO)
+- [ ] Fasting requirements matched (fasting glucose, lipids)
+- [ ] Age restrictions applied correctly
+- [ ] Code runs without errors on target data
+- [ ] Output tables match source paper structure
+
+## Critical Rules
+
+1. **Never pool data across surveys**. Analyze each country's data with its own survey design.
+2. **Document every deviation** from the source methodology in the difference report.
+3. **Asian BMI cutoffs** (≥25 for obesity) when analyzing Korean data, even if source used WHO (≥30).
+4. **LDL calculation**: note if source used direct measurement vs Friedewald.
+5. **Weighted analysis is mandatory** for KNHANES/NHANES — never run unweighted models.
+6. **IRB**: note that KNHANES/NHANES are de-identified public data (IRB exempt or waived).
+7. **Outdated source definitions**: if the source paper used a pre-2023 definition that has since been superseded (e.g., NAFLD → MASLD 2023, CKD-EPI 2009 → 2021 race-free), call `/define-variables` to cross-check whether to mirror the legacy definition (pure replication) or upgrade to current (extension). Document the choice explicitly in the difference report.
+
+## Output Files
+
+```
+{working_dir}/
+├── replication_report.md     — Structured difference report
+├── variable_mapping.csv      — Variable mapping table with match status
+├── analysis_code.py          — Main analysis script (Python + R calls)
+├── analysis_code.R           — R script for survey-weighted analysis
+└── results/
+    ├── table1.csv            — Demographics table
+    ├── main_results.csv      — Primary analysis results
+    └── subgroup_results.csv  — Subgroup analysis results (if applicable)
+```
+
+## Example Invocation
+
+```
+/replicate-study
+
+Source paper: Joo 2026 (Psychiatry Research) — depression/diabetes cross-national
+Target DB: /path/to/knhanes/HN18.csv
+Harmonization: /path/to/harmonization_knhanes_nhanes.csv
+```
+
+## Anti-Hallucination
+
+- **Never fabricate variable names, dataset column names, or variable codings.** If a variable mapping is uncertain, output `[VERIFY: variable_name]` and ask the user to confirm against the data dictionary.
+- **Never fabricate statistical results** — no invented p-values, effect sizes, confidence intervals, or sample sizes. All numbers must come from executed code output.
+- **Never generate references from memory.** Use `/search-lit` for all citations.
+- If a function, package, or API does not exist or you are unsure, say so explicitly rather than guessing.

package/skills/replicate-study/references/harmonization_3country.csv

@@ -0,0 +1,47 @@
+domain,concept,concept_en,knhanes_var,knhanes_label,knhanes_years,nhanes_table_J,nhanes_table_P,nhanes_var,nhanes_label,chns_file,chns_var,chns_label,chns_waves,harmonization_notes
+demographics,ID,ID,ID,개인아이디,2007-2024,DEMO_J,P_DEMO,SEQN,Respondent sequence number,mast_pub_12,IDind,Individual ID,1989-2015,"Primary key — not linkable across surveys. KNHANES 2007-2009 uses lowercase 'id'"
+demographics,조사연도,Survey year,year,조사연도,2007-2024,DEMO_J,P_DEMO,SDDSRVYR,Data release cycle number,all,wave,Survey wave,1989-2015,"KNHANES=calendar year; NHANES=cycle number; CHNS=wave year"
+demographics,성별,Sex,sex,성별 (1=남 2=여),2007-2024,DEMO_J,P_DEMO,RIAGENDR,Gender (1=Male 2=Female),mast_pub_12,GENDER,Gender (1=male 2=female),1989-2015,"Direct match: 1=Male 2=Female (all three)"
+demographics,나이,Age,age,만나이,2007-2024,DEMO_J,P_DEMO,RIDAGEYR,Age in years at screening,mast_pub_12,WEST_DOB_Y,Western Date of Birth YYYY,1989-2015,"CHNS: derive age = wave_year - WEST_DOB_Y. Truncation to integer."
+demographics,인종/민족,Race/ethnicity,—,없음 (단일민족),—,DEMO_J,P_DEMO,RIDRETH3,Race/Hispanic origin w/ NH Asian,mast_pub_12,NATIONALITY,Nationality (Han=1),1989-2015,"KNHANES/CHNS lack race; set country indicator instead. CHNS: 95% Han, can stratify"
+demographics,가구소득,Household income,incm,소득4분위수(개인),2007-2024,DEMO_J,P_DEMO,INDFMPIR,Ratio of family income to poverty,indinc_10,indwage,Individual wage income (yuan),1989-2015,"Recode all to quartiles within each country. CHNS: continuous yuan→quartiles within wave"
+demographics,교육수준,Education,edu,교육수준 재분류 코드,2007-2024,DEMO_J,P_DEMO,DMDEDUC2,Education level - Adults 20+,educ_12,A12,Highest education level (0-6),1989-2015,"Harmonize to 3-level: ≤HS / Some college / ≥College. CHNS A12: 0=none 1=primary 2=lower-mid 3=upper-mid 4=tech/vocational 5=university 6=master+. Recode: 0-2→low 3-4→mid 5-6→high"
+demographics,결혼상태,Marital status,marri_2,결혼상태,2007-2024,DEMO_J,P_DEMO,DMDMARTZ,Marital status,—,—,Not in standard download,—,"CHNS: available in surveys_pub_12 but coding needs verification"
+demographics,가중치(설문+검진),Sample weight (interview+exam),wt_itvex,설문검진조사 가중치,2007-2024,DEMO_J,P_DEMO,WTMEC2YR / WTMECPRP,Full sample MEC exam weight,—,—,No formal survey weight,—,"KNHANES: wt_itvex (÷N_years for pooled). NHANES: WTMEC2YR (single) / WTMECPRP (pre-pandemic). CHNS: no formal survey weights — use unweighted with robust SE clustered by communityID"
+demographics,층화변수,Stratification,kstrata,분산추정 층,2007-2024,DEMO_J,P_DEMO,SDMVSTRA,Masked variance pseudo-stratum,—,—,No stratification variable,—,"CHNS: no formal stratification. Use province (T1) as stratification if needed"
+demographics,집락변수,Cluster (PSU),psu,조사구번호,2007-2024,DEMO_J,P_DEMO,SDMVPSU,Masked variance pseudo-PSU,pexam_00/hlth_12,COMMID,Community ID (T1-T4),1989-2015,"CHNS: COMMID is the primary sampling unit"
+exam,신장,Height (cm),HE_ht,신장,2007-2024,BMX_J,P_BMX,BMXHT,Standing height (cm),pexam_00,HEIGHT,Height (cm),1989-2011,"Direct match"
+exam,체중,Weight (kg),HE_wt,체중,2007-2024,BMX_J,P_BMX,BMXWT,Weight (kg),pexam_00,WEIGHT,Weight (kg),1989-2011,"Direct match"
+exam,BMI,BMI (kg/m²),HE_BMI,체질량지수,2007-2024,BMX_J,P_BMX,BMXBMI,Body mass index (kg/m²),pexam_00,—,Derive BMI=WEIGHT/(HEIGHT/100)^2,1989-2011,"Direct match KR/US. CHNS: derive. Obesity cutoffs: KR≥25 / US≥30 / CN≥28 (WGOC)"
+exam,허리둘레,Waist circumference (cm),HE_wc,허리둘레,2007-2024,BMX_J,P_BMX,BMXWAIST,Waist circumference (cm),pexam_00,U10,Waist circumference (cm),1993-2011,"Direct match. Central obesity: KR≥90M/85F / US≥102M/88F / CN≥90M/80F (IDF-Asian)"
+exam,수축기혈압,Systolic BP (mmHg),HE_sbp,최종 수축기 혈압,2007-2024,BPXO_J,P_BPXO,BPXOSY3,Systolic: Average oscillometric,pexam_00,SYSTOL1-3,Systolic BP 3 readings,1991-2011,"All use average of readings. CHNS: mean(SYSTOL1 SYSTOL2 SYSTOL3)"
+exam,이완기혈압,Diastolic BP (mmHg),HE_dbp,최종 이완기 혈압,2007-2024,BPXO_J,P_BPXO,BPXODI3,Diastolic: Average oscillometric,pexam_00,DIASTOL1-3,Diastolic BP 3 readings,1991-2011,"Same protocol. CHNS: mean(DIASTOL1 DIASTOL2 DIASTOL3)"
+exam,고혈압,Hypertension status,HE_HP,고혈압 유병여부,2007-2024,BPX_J+BPQ_J,P_BPXO+P_BPQ,BPXOSY3+BPQ020,SBP/DBP + told HBP,pexam_00,U22+U24+BP,Dx + meds + measured BP,1991-2011,"Define uniformly: SBP≥140 or DBP≥90 or U22==1 (diagnosed) or U24==1 (on meds)"
+lab,공복혈당,Fasting glucose (mg/dL),HE_glu,공복혈당,2007-2024,BIOPRO_J,P_BIOPRO,LBXSGL,Glucose: refrigerated serum (mg/dL),biomarker_09,GLUCOSE_MG,Blood Glucose (mg/dL),2009,"Direct match. CHNS also has mmol/L version (GLUCOSE). Available 2009 wave only"
+lab,당화혈색소,HbA1c (%),HE_HbA1c,당화혈색소,2007-2024,GHB_J,P_GHB,LBXGH,Glycohemoglobin (%),biomarker_09,HbA1c,HbA1c (%),2009,"Direct match. Available 2009 wave only"
+lab,당뇨병,Diabetes status,HE_DM,당뇨병 유병여부,2007-2024,GHB_J+BIOPRO_J+DIQ_J,P_GHB+P_BIOPRO+P_DIQ,LBXGH+LBXSGL+DIQ010,HbA1c+FPG+told DM,biomarker_09+pexam_00,GLUCOSE_MG+HbA1c+U24A,Lab+dx,2009,"Define uniformly: FPG≥126 or HbA1c≥6.5 or U24A==1 (diagnosed). CHNS: biomarker only 2009"
+lab,총콜레스테롤,Total cholesterol (mg/dL),HE_chol,총콜레스테롤,2007-2024,TCHOL_J,P_TCHOL,LBXTC,Total cholesterol (mg/dL),biomarker_09,TC_MG,Total cholesterol (mg/dL),2009,"Direct match"
+lab,HDL콜레스테롤,HDL cholesterol (mg/dL),HE_HDL_st2,HDL-콜레스테롤,2007-2024,HDL_J,P_HDL,LBDHDD,Direct HDL-Cholesterol (mg/dL),biomarker_09,HDL_C_MG,HDL-C (mg/dL),2009,"Direct match"
+lab,중성지방,Triglycerides (mg/dL),HE_TG,중성지방,2007-2024,BIOPRO_J,P_BIOPRO,LBXSTR,Triglycerides (mg/dL),biomarker_09,TG_MG,Triglycerides (mg/dL),2009,"Direct match (fasting)"
+lab,LDL콜레스테롤,LDL cholesterol (mg/dL),—,없음 (계산값),—,TRIGLY_J,P_TRIGLY,LBDLDL,LDL-cholesterol (mg/dL),biomarker_09,LDL_C_MG,LDL-C (mg/dL),2009,"KR: derive from Friedewald. US: direct or calculated. CN: direct measurement"
+lab,AST,AST (IU/L),HE_ast,AST(SGOT),2007-2024,BIOPRO_J,P_BIOPRO,LBXSASSI,AST (IU/L),—,—,Not available,—,"CHNS biomarker panel does not include AST"
+lab,ALT,ALT (IU/L),HE_alt,ALT(SGPT),2007-2024,BIOPRO_J,P_BIOPRO,LBXSATSI,ALT (IU/L),biomarker_09,ALT,ALT (U/L),2009,"Direct match"
+lab,크레아티닌,Creatinine (mg/dL),HE_crea,혈중크레아티닌,2007-2024,BIOPRO_J,P_BIOPRO,LBXSCR,Creatinine (mg/dL),biomarker_09,CRE_MG,Creatinine (mg/dL),2009,"Direct match (CHNS has both umol/L and mg/dL)"
+lab,헤모글로빈,Hemoglobin (g/dL),HE_HB,헤모글로빈,2007-2024,CBC_J,P_CBC,LBXHGB,Hemoglobin (g/dL),biomarker_09,HGB,Hemoglobin (g/L),2009,"CHNS unit is g/L — divide by 10 to convert to g/dL"
+lab,백혈구,WBC (10³/µL),HE_WBC,백혈구,2007-2024,CBC_J,P_CBC,LBXWBCSI,WBC (1000 cells/µL),biomarker_09,WBC,WBC (x10^9 cells/L),2009,"Direct match (same unit: 10^3/µL = 10^9/L)"
+lab,hsCRP,hsCRP (mg/L),HE_hsCRP,고감도CRP,2007-2024,HSCRP_J,P_HSCRP,LBXHSCRP,HS CRP (mg/L),biomarker_09,HS_CRP,High-sensitivity CRP (mg/L),2009,"Direct match"
+questionnaire,우울증(PHQ-9),Depression (PHQ-9),BP_PHQ_1~9 / mh_PHQ_S,PHQ-9 문항1-9 / 총점,2014/16/18/20/22/24 (even years),DPQ_J,P_DPQ,DPQ010~DPQ090,PHQ-9 items,—,—,CES-D (NOT in this download),—,"CRITICAL: KR/US use identical PHQ-9. CHNS uses CES-D — NOT in current download. Need separate CHNS CES-D dataset from cpc.unc.edu. For 3-country: use binary depression cutoff as sensitivity analysis"
+questionnaire,흡연상태,Smoking status,BS3_1,현재흡연여부,2007-2024,SMQ_J,P_SMQ,SMQ020+SMQ040,Smoked 100 cigs + now smoke,pexam_00,U25+U27,Ever smoked + Still smokes,1989-2011,"Derive: never(U25==0)/former(U25==1 & U27==0)/current(U25==1 & U27==1). KNHANES BS3_1 (not BS1_1)"
+questionnaire,음주빈도,Alcohol frequency,BD1_11,1년간 음주빈도,2007-2024,ALQ_J,P_ALQ,ALQ121,Past 12 mo how often drink,pexam_00,U40+U41,Drank last year + frequency,1989-2011,"CHNS U40: 0=no 1=yes. U41: 1=almost daily 2=3-4x/wk 3=1-2x/wk 4=1-2x/mo 5=<1x/mo. Recode to: never(U40==0) / occasional(U41≥4) / frequent(U41≤3)"
+questionnaire,신체활동,Physical activity,pa_aerobic,유산소 신체활동,2007-2024,PAQ_J,P_PAQ,PAQ605+PAQ620,Vigorous/moderate activity,—,—,Not in biomarker wave,—,"CHNS has PA in some waves but not aligned with biomarker 2009. Omit for 3-country biomarker analysis"
+questionnaire,당뇨진단,Diabetes diagnosis,DE1_dg,당뇨병 의사진단,2007-2024,DIQ_J,P_DIQ,DIQ010,Doctor told diabetes,pexam_00,U24A,Diagnosed with diabetes (0/1),1997-2011,"Direct match (yes/no). CHNS: 0=no 1=yes 9=don't know"
+questionnaire,고혈압진단,Hypertension diagnosis,DI1_dg,고혈압 의사진단,2007-2024,BPQ_J,P_BPQ,BPQ020,Ever told high BP,pexam_00,U22,Diagnosed with HBP (0/1),1991-2011,"Direct match. CHNS: 0=no 1=yes 9=don't know"
+questionnaire,주관적건강,Self-rated health,D_1_1,주관적 건강상태,2007-2024,HUQ_J,P_HUQ,HUQ010,General health condition,pexam_00,U48A,Current health status (self-report),2004-2011,"All use Likert scale. Cultural response bias — report as supplementary"
+questionnaire,체중조절,Weight control attempt,BO2_1,체중조절여부,2007-2024,WHQ_J,P_WHQ,WHQ150,Tried to lose weight,—,—,Not available,—,"CHNS: not in standard questionnaire"
+questionnaire,수면시간,Sleep duration,Total_slp_wk,주중 수면시간,2007-2024,SLQ_J,P_SLQ,SLD012,Sleep hours weekdays,—,—,Not in standard download,—,"CHNS: sleep data in time-use file but not aligned with biomarker wave"
+survey_design,가중치안내,Weight guidance,—,—,—,—,—,—,—,—,—,—,—,"CRITICAL: Never pool raw data across countries. Analyze each country separately with own survey design then compare estimates."
+survey_design,복합표본(한국),Complex survey (Korea),kstrata+psu+wt_itvex,층+집락+가중치,—,—,—,—,—,—,—,—,—,"svydesign(id=~psu, strata=~kstrata, weights=~wt_pooled, nest=TRUE). wt_pooled=wt_itvex/N_years"
+survey_design,복합표본(미국),Complex survey (US),—,—,—,DEMO_J,P_DEMO,SDMVSTRA+SDMVPSU+WTMEC2YR/WTMECPRP,Strata+PSU+Weight,—,—,—,—,"Single cycle: WTMEC2YR. Pre-pandemic: WTMECPRP. svydesign(id=~SDMVPSU, strata=~SDMVSTRA, weights=~weight, nest=TRUE)"
+survey_design,복합표본(중국),Complex survey (China),—,—,—,—,—,—,—,pexam_00/hlth_12,COMMID,Community cluster,1989-2015,"CHNS: no formal survey weights. Use communityID as cluster. svydesign(id=~COMMID, weights=~1) or glm with cluster-robust SE"
+survey_design,비만기준차이,Obesity cutoffs by country,—,—,—,—,—,—,—,—,—,—,—,"KR: BMI≥25 (KSSO). US: BMI≥30 (CDC/WHO). CN: BMI≥28 (WGOC). Central obesity: KR≥90M/85F. US≥102M/88F. CN≥90M/80F (IDF-Asian)"
+survey_design,우울증도구차이,Depression instrument difference,—,—,—,—,—,—,—,—,—,—,—,"KR/US: PHQ-9 (identical, directly comparable). CN: CES-D (not directly comparable, not in current download). For 3-country comparison: use binary depression (cutoff-based) as sensitivity analysis or omit CN depression"

package/skills/replicate-study/references/harmonization_knhanes_nhanes.csv

@@ -0,0 +1,68 @@
+domain,concept,concept_en,knhanes_var,knhanes_label,nhanes_table,nhanes_var,nhanes_label,harmonization_notes
+demographics,ID,ID,ID,개인아이디,DEMO_J,SEQN,Respondent sequence number,"Primary key — not linkable across surveys. CRITICAL: nhanesA R package exports TEXT LABELS not numeric codes. PHQ-9='Not at all'/0, Sex='Male'/'Female', Smoking='Yes'/'No'. WTMEC2YR for single-cycle, WTMECPRP for pre-pandemic pooled. Glucose=LBXSGL (not LBXSGLU)."
+demographics,조사연도,Survey year,year,조사연도,DEMO_J,SDDSRVYR,Data release cycle number,KNHANES=calendar year; NHANES=cycle number
+demographics,성별,Sex,sex,성별 (1=남 2=여),DEMO_J,RIAGENDR,Gender (1=Male 2=Female),Direct match: 1=Male 2=Female
+demographics,나이,Age,age,만나이,DEMO_J,RIDAGEYR,Age in years at screening,Direct match (continuous)
+demographics,인종/민족,Race/ethnicity,—,없음 (단일민족),DEMO_J,RIDRETH3,Race/Hispanic origin w/ NH Asian,KNHANES lacks race; set country indicator instead
+demographics,가구소득,Household income,incm,소득4분위수(개인),DEMO_J,INDFMPIR,Ratio of family income to poverty,Recode: KNHANES quartile vs NHANES PIR ratio — harmonize to quartiles
+demographics,교육수준,Education,edu,교육수준 재분류 코드,DEMO_J,DMDEDUC2,Education level - Adults 20+,Recode: KNHANES 4-level → NHANES 5-level → harmonize to 3-level (≤HS/Some college/≥College)
+demographics,결혼상태,Marital status,marri_2,결혼상태,DEMO_J,DMDMARTZ,Marital status,Recode both to: married-cohabiting / single-divorced-widowed
+demographics,가중치(설문+검진),Sample weight (interview+exam),wt_itvex,설문검진조사 가중치,DEMO_J,WTMECPRP,Full sample MEC exam weight,Use survey-appropriate weight; never pool raw weights
+demographics,층화변수,Stratification,kstrata,분산추정 층,DEMO_J,SDMVSTRA,Masked variance pseudo-stratum,Required for complex survey analysis
+demographics,집락변수,Cluster (PSU),psu,조사구번호,DEMO_J,SDMVPSU,Masked variance pseudo-PSU,Required for complex survey analysis
+exam,신장,Height (cm),HE_ht,신장,BMX_J,BMXHT,Standing height (cm),Direct match
+exam,체중,Weight (kg),HE_wt,체중,BMX_J,BMXWT,Weight (kg),Direct match
+exam,BMI,BMI (kg/m²),HE_BMI,체질량지수,BMX_J,BMXBMI,Body mass index (kg/m²),Direct match
+exam,비만,Obesity status,HE_obe,비만 유병여부,BMX_J,BMXBMI,BMI,KNHANES uses Asian criteria (≥25); NHANES uses WHO (≥30). Report both.
+exam,허리둘레,Waist circumference (cm),HE_wc,허리둘레,BMX_J,BMXWAIST,Waist circumference (cm),Direct match (measurement protocol may differ slightly)
+exam,수축기혈압,Systolic BP (mmHg),HE_sbp,최종 수축기 혈압(2+3차 평균),BPX_J,BPXOSY3,Systolic: Average oscillometric,Both use average of 2nd+3rd readings
+exam,이완기혈압,Diastolic BP (mmHg),HE_dbp,최종 이완기 혈압(2+3차 평균),BPX_J,BPXODI3,Diastolic: Average oscillometric,Both use average of 2nd+3rd readings
+exam,고혈압,Hypertension status,HE_HP,고혈압 유병여부,BPX_J+BPQ_J,BPXOSY3+BPQ020,SBP/DBP + told HBP,Define uniformly: SBP≥140 or DBP≥90 or medication
+exam,맥박,Pulse rate (bpm),HE_mPLS,60초 맥박수,BPX_J,BPXOPULS3,Pulse: Average oscillometric,Direct match
+lab,공복혈당,Fasting glucose (mg/dL),HE_glu,공복혈당,BIOPRO_J,LBXSGL,Glucose: refrigerated serum (mg/dL),"Direct match (both fasting). CRITICAL: variable is LBXSGL not LBXSGLU in BIOPRO_J"
+lab,당화혈색소,HbA1c (%),HE_HbA1c,당화혈색소,GHB_J,LBXGH,Glycohemoglobin (%),Direct match
+lab,당뇨병,Diabetes status,HE_DM,당뇨병 유병여부,GHB_J+BIOPRO_J+DIQ_J,LBXGH+LBXSGL+DIQ010,HbA1c+FPG+told DM,Define uniformly: FPG≥126 or HbA1c≥6.5 or medication or diagnosed
+lab,총콜레스테롤,Total cholesterol (mg/dL),HE_chol,총콜레스테롤,TCHOL_J,LBXTC,Total cholesterol (mg/dL),Direct match
+lab,HDL콜레스테롤,HDL cholesterol (mg/dL),HE_HDL_st2,HDL-콜레스테롤,HDL_J,LBDHDD,Direct HDL-Cholesterol (mg/dL),Direct match
+lab,중성지방,Triglycerides (mg/dL),HE_TG,중성지방,BIOPRO_J,LBXSTR,Triglycerides: refrigerated serum (mg/dL),Direct match (fasting)
+lab,LDL콜레스테롤,LDL cholesterol (mg/dL),HE_LDL_drct,LDL-콜레스테롤(직접검사),BIOPRO_J,LBDLDL,LDL-Cholesterol (mg/dL),KNHANES=direct; NHANES=Friedewald calculation. Note in Methods.
+lab,이상지질혈증,Dyslipidemia,HE_HCHOL,고콜레스테롤혈증 유병여부,TCHOL_J+BPQ_J,LBXTC+BPQ080,TC + told high chol,Define uniformly: TC≥240 or medication
+lab,AST,AST (IU/L),HE_ast,AST(SGOT),BIOPRO_J,LBXSASSI,AST (IU/L),Direct match
+lab,ALT,ALT (IU/L),HE_alt,ALT(SGPT),BIOPRO_J,LBXSATSI,ALT (IU/L),Direct match
+lab,BUN,BUN (mg/dL),HE_BUN,혈중요소질소,BIOPRO_J,LBXSBU,Blood urea nitrogen (mg/dL),Direct match
+lab,크레아티닌,Creatinine (mg/dL),HE_crea,혈중크레아티닌,BIOPRO_J,LBXSCR,Creatinine: refrigerated serum (mg/dL),Direct match; derive eGFR with CKD-EPI
+lab,요산,Uric acid (mg/dL),HE_Uacid,요산,BIOPRO_J,LBXSUA,Uric acid (mg/dL),Direct match
+lab,hsCRP,hsCRP (mg/L),HE_hsCRP,고감도 C반응단백검사,HSCRP_J,LBXHSCRP,HS C-Reactive Protein (mg/L),Direct match
+lab,헤모글로빈,Hemoglobin (g/dL),HE_HB,헤모글로빈,CBC_J,LBXHGB,Hemoglobin (g/dL),Direct match
+lab,헤마토크리트,Hematocrit (%),HE_HCT,헤마토크리트,CBC_J,LBXHCT,Hematocrit (%),Direct match
+lab,백혈구,WBC (10³/µL),HE_WBC,백혈구,CBC_J,LBXWBCSI,White blood cell count (1000 cells/µL),Direct match
+lab,적혈구,RBC (10⁶/µL),HE_RBC,적혈구,CBC_J,LBXRBCSI,Red blood cell count (million cells/µL),Direct match
+lab,혈소판,Platelet (10³/µL),HE_Bplt,혈소판,CBC_J,LBXPLTSI,Platelet count (1000 cells/µL),Direct match
+lab,빈혈,Anemia status,HE_anem,빈혈 유병여부,CBC_J,LBXHGB,Hemoglobin,Define uniformly: male Hb<13 / female Hb<12 (WHO criteria)
+lab,요단백,Urine protein,HE_Upro,요단백,ALB_CR_J,URXUMA,Albumin urine (µg/mL),KNHANES=dipstick qualitative; NHANES=quantitative albumin. Use ACR for both.
+lab,요크레아티닌,Urine creatinine,HE_UCREA,요크레아티닌,ALB_CR_J,URXUCR,Creatinine urine (mg/dL),Direct match; use for ACR calculation
+lab,B형간염표면항원,HBsAg,HE_HBsAg,B형간염표면항원(수치),—,—,Not in 2017-2018 NHANES,NHANES Hepatitis B (HEPB_S_J) tests surface antibody not antigen
+lab,C형간염항체,Anti-HCV,HE_hcv,C형간염항체(수치),HEPC_J,LBXHCR,Hepatitis C antibody,Qualitative match (positive/negative)
+questionnaire,우울증(PHQ-9),Depression (PHQ-9),BP_PHQ_1~9 / mh_PHQ_S,PHQ-9 문항1-9 / PHQ-9점수,DPQ_J,DPQ010~DPQ090,PHQ-9 items,Identical instrument (PHQ-9). Sum scores directly comparable.
+questionnaire,자살생각,Suicidal ideation,BP6_10,1년간 자살 생각 여부,DPQ_J,DPQ090,PHQ-9 Q9 (thoughts of death),KNHANES=dedicated question; NHANES=PHQ-9 Q9 only. Not perfectly matched.
+questionnaire,스트레스,Perceived stress,BP1,평소 스트레스 인지 정도,—,—,—,No direct NHANES equivalent. Consider excluding or using PHQ-4.
+questionnaire,흡연상태,Smoking status,BS3_1(현재흡연상태),현재흡연상태(1=매일/2=가끔/3=과거/8=비해당),SMQ_J,SMQ020+SMQ040,Smoked 100 cigs + now smoke,"Derive: BS3_1 in (1,2)=current, 3=former, 8=never. NOT BS1_1."
+questionnaire,음주빈도,Alcohol frequency,BD1_11,1년간 음주빈도(1=전혀/2=월1미만/3=월1/4=월2-4/5=주2-3/6=주4+/8=비해당),ALQ_J,ALQ121,Past 12 mo how often drink,"Joo2026 coding: 2-6=Frequent(current drinker), 1=Occasional(past-year abstainer), 8=Never(lifetime non-drinker)"
+questionnaire,음주량,Alcohol amount per occasion,BD2_1,한번에 마시는 음주량,ALQ_J,ALQ130,Avg # drinks/day past 12 mo,KNHANES=drinks/occasion; NHANES=drinks/day. Harmonize to standard drinks.
+questionnaire,신체활동(유산소),Aerobic physical activity,BE3_71~BE3_91 / pa_aerobic,유산소신체활동실천율,PAQ_J,PAQ605+PAQ620+PAD645+PAD660,Vigorous/moderate work/recreation min,Both use GPAQ/IPAQ framework. Derive WHO ≥150 min moderate criterion.
+questionnaire,수면시간(주중),Sleep duration (weekday),Total_slp_wk,주중 하루 평균 수면시간,SLQ_J,SLD012,Sleep hours - weekdays,Direct match (hours)
+questionnaire,수면시간(주말),Sleep duration (weekend),Total_slp_wd,주말 하루 평균 수면시간,SLQ_J,SLD013,Sleep hours - weekends,Direct match (hours)
+questionnaire,당뇨진단,Diabetes diagnosis,DE1_dg,당뇨병 의사진단여부,DIQ_J,DIQ010,Doctor told you have diabetes,Direct match (yes/no)
+questionnaire,고혈압진단,Hypertension diagnosis,DI1_dg,고혈압 의사진단여부,BPQ_J,BPQ020,Ever told you had high blood pressure,Direct match (yes/no)
+questionnaire,이상지질혈증진단,Dyslipidemia diagnosis,DI2_dg,이상지질혈증 의사진단여부,BPQ_J,BPQ080,Doctor told you have high cholesterol,Direct match (yes/no)
+questionnaire,천식진단,Asthma diagnosis,DJ4_dg,천식 의사진단여부,MCQ_J,MCQ010,Ever been told you have asthma,Direct match (yes/no)
+questionnaire,뇌졸중진단,Stroke diagnosis,DI3_dg,뇌졸중 의사진단여부,MCQ_J,MCQ160F,Ever told you had a stroke,Direct match (yes/no)
+questionnaire,심근경색진단,MI diagnosis,DI5_dg,심근경색증 의사진단여부,MCQ_J,MCQ160E,Ever told you had heart attack,Direct match (yes/no)
+questionnaire,암진단,Cancer diagnosis,DC1_dg~DC7_dg,위암~갑상선암 의사진단,MCQ_J,MCQ220,Ever told you had cancer/malignancy,KNHANES=site-specific; NHANES=any cancer. Recode to ever-cancer for comparison.
+questionnaire,체중조절,Weight control attempt,BO2_1,1년간 체중 조절 여부,WHQ_J,WHQ150,Tried to lose weight past 12 mo,Direct match (yes/no)
+questionnaire,주관적건강,Self-rated health,D_1_1,주관적 건강상태,HUQ_J,HUQ010,General health condition,Both use 5-level Likert. Direct match.
+questionnaire,건강보험,Health insurance,tins,건강보험종류,HIQ_J,HIQ011,Covered by health insurance,KNHANES: NHI universal; NHANES: varies. Set as country-level variable.
+questionnaire,EQ-5D,Quality of life (EQ-5D),EQ5D,EQ-5D index,—,—,—,NHANES does not include EQ-5D. KNHANES-only variable.
+survey_design,가중치안내,Weight guidance,—,—,—,—,—,"CRITICAL: Never pool raw data. Analyze each country separately with its own survey design, then compare estimates."
+survey_design,복합표본설계(한국),Complex survey (Korea),kstrata + psu + wt_itvex,층 + 집락 + 가중치,—,—,—,"svydesign(id=~psu, strata=~kstrata, weights=~wt_itvex, nest=TRUE)"
+survey_design,복합표본설계(미국),Complex survey (US),—,—,DEMO_J,SDMVSTRA + SDMVPSU + WTMECPRP,Strata + PSU + Weight,"svydesign(id=~SDMVPSU, strata=~SDMVSTRA, weights=~WTMECPRP, nest=TRUE)"

package/skills/replicate-study/references/methodology_extraction_template.md

@@ -0,0 +1,134 @@
+# Methodology Extraction Template
+
+Use this checklist to systematically extract a source paper's methodology for replication.
+
+## 1. Study Overview
+
+| Field | Value |
+|-------|-------|
+| Title | |
+| Authors | |
+| Journal / Year | |
+| DOI | |
+| Study type | cohort / cross-sectional / case-control / other |
+| Design variant | emulated target trial / standard / trend / composite |
+
+## 2. Database
+
+| Field | Value |
+|-------|-------|
+| Database name | |
+| Country | |
+| Data years | |
+| Total N (before exclusions) | |
+| Final analytic N | |
+| Population-based? | yes / no |
+| Survey design? | yes (complex) / no |
+| Weights variable | |
+| Strata variable | |
+| PSU/cluster variable | |
+
+## 3. Study Population
+
+### Inclusion Criteria
+- [ ] Age range: 
+- [ ] Sex: both / male / female
+- [ ] Fasting: required (≥N hours) / not required
+- [ ] Exam participation: required / not required
+- [ ] Other: 
+
+### Exclusion Criteria
+- [ ] Missing key variables: 
+- [ ] Pregnant women: excluded / included
+- [ ] Prior disease: 
+- [ ] Age outliers: 
+- [ ] Other: 
+
+## 4. Exposure Variable
+
+| Field | Value |
+|-------|-------|
+| Concept | |
+| Variable name(s) | |
+| Definition | |
+| Coding | binary / categorical / continuous |
+| Categories | |
+| Source (questionnaire/lab/exam) | |
+
+## 5. Outcome Variable
+
+| Field | Value |
+|-------|-------|
+| Concept | |
+| Variable name(s) | |
+| Definition | |
+| Coding | binary / categorical / continuous |
+| Source (questionnaire/lab/exam) | |
+| For composite outcomes, list components: | |
+
+## 6. Covariates
+
+List ALL covariates used in any model:
+
+| # | Covariate | Definition | Variable(s) | Coding | Model(s) |
+|---|-----------|------------|-------------|--------|----------|
+| 1 | Age | | | continuous / categorical | all |
+| 2 | Sex | | | binary | all |
+| 3 | | | | | |
+
+## 7. Statistical Methods
+
+### Primary Analysis
+| Field | Value |
+|-------|-------|
+| Model type | logistic / Cox / linear / Poisson / other |
+| Dependent variable | |
+| Key independent variable | |
+| Adjustment strategy | sequential (Model 1/2/3) / full / stepwise |
+
+### Model Building (if sequential)
+| Model | Covariates |
+|-------|-----------|
+| Model 1 (unadjusted or age/sex) | |
+| Model 2 (+ sociodemographic) | |
+| Model 3 (+ clinical/behavioral) | |
+
+### Effect Measure
+- OR / aOR / HR / aHR / PR / β / wOR
+- 95% CI reported: yes / no
+- P-value threshold: 
+
+### Subgroup Analyses
+| Subgroup variable | Categories |
+|-------------------|-----------|
+| | |
+
+### Sensitivity Analyses
+| # | Description |
+|---|-------------|
+| 1 | |
+| 2 | |
+
+## 8. Key Results to Replicate
+
+| Analysis | Effect (95% CI) | P-value | Note |
+|----------|----------------|---------|------|
+| Primary | | | |
+| Subgroup 1 | | | |
+| Sensitivity 1 | | | |
+
+## 9. Tables/Figures to Replicate
+
+| # | Type | Description |
+|---|------|-------------|
+| Table 1 | Demographics | Baseline characteristics by exposure |
+| Table 2 | Main results | OR/HR with sequential models |
+| | | |
+
+## 10. IRB / Ethics
+
+| Field | Value |
+|-------|-------|
+| Original IRB | |
+| Target DB IRB status | exempt (de-identified public data) / needs new IRB |
+| Informed consent | waived (secondary data) |

package/skills/replicate-study/skill.yml

@@ -0,0 +1,37 @@
+schema_version: 2
+name: replicate-study
+layer: B
+owner_domain: study_replication
+
+when_to_use: "Replicate an existing cohort study's methodology on a different database via a variable harmonization table and a replication difference report."
+when_NOT_to_use: "Comparing countries in parallel (use cross-national); a fresh single analysis (use analyze-stats)."
+
+inputs:
+  - "source study paper"
+  - "target database"
+  - "variable mapping"
+outputs:
+  - "replication analysis code"
+  - "replication difference report"
+side_effects:
+  - writes_project_artifacts
+  - executes_analysis_code
+downstream_consumers:
+  - analyze-stats
+  - self-review
+forbidden_actions:
+  - misrepresent_method_deviations_as_identical
+  - fabricate_replication_results
+
+# v2.1 quality card
+purpose: "Re-run a published study's method on a new DB and report exactly where target-DB constraints forced deviations."
+safety_boundaries:
+  - "Method deviations forced by the target DB are documented in a difference report, not hidden."
+  - "Results come from executed code on the target data."
+known_limitations:
+  - "Perfect replication is rarely possible; residual method differences remain and are disclosed."
+  - "No standalone demo; depends on a faithful variable mapping."
+validation_commands:
+  - "execute the replication code and review the difference report"
+  - "/self-review"
+evidence_surface: manual_workflow

package/skills/review-paper/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: review-paper
+description: >
+  Scaffold and draft medical/AI literature reviews (narrative, scoping PRISMA-ScR, or systematic). Asks for
+  the spine axis, builds a 7-part skeleton with a required Intro scope/non-overlap block, a summary-table stub,
+  an evaluation-metrics critique subsection, and reporting-guideline wiring. Reuses the self-review RV1-RV8
+  narrative-review probes for QC. Does not invent citations.
+triggers: review article, scoping review, narrative review, literature review, PRISMA-ScR, write a review
+tools: Read, Write, Edit, Bash, Grep, Glob
+model: inherit
+---
+
+# Review-Paper Skill
+
+Scaffold and draft a **literature review** — narrative, scoping (PRISMA-ScR), or systematic
+(PRISMA 2020) — for medical / medical-AI research. This skill builds the structure, the
+required scope/non-overlap framing, the summary-table stubs, and the reporting-guideline
+wiring, then hands off to the existing QC skills. It is the review-article counterpart to
+`write-paper` (which targets original research); for *reviewing* someone else's review
+article, use `/peer-review` or `/self-review` (the RV1-RV8 probes). The structure follows
+established review-writing conventions; it is not derived from, and does not reproduce, any
+specific published review.
+
+## Anti-Hallucination
+
+- **Never invent citations.** Every citekey must resolve to the project's verified
+  `_src/refs.bib` (produced by `/search-lit` → `/lit-sync` → `/verify-refs`). If a claim
+  needs a reference that is not yet in the library, leave a `[NEEDS-REF: claim]` marker and
+  route it to `/search-lit`; do not fabricate a DOI, author, year, or citekey.
+- **Never invent data.** Summary-table cells (study, year, metric, finding) are filled only
+  from sources the user supplies or that are verified; an unknown cell stays a placeholder.
+- **No recommendation-grade language without standing.** For a scoping review especially,
+  the output maps the evidence — it does not issue clinical recommendations.
+- **Quality gate before hand-off:** the draft is not "done" until `/self-review` reports 0
+  fatal findings and `/verify-refs` reports 0 FABRICATED / MISMATCH and no placeholder
+  citations remain.
+
+## Step 0 — Format + spine axis (the structure-determining choice)
+
+1. Confirm **format** with the user: narrative (SANRA) | scoping (PRISMA-ScR + JBI) |
+   systematic (PRISMA 2020). This decides the reporting guideline and the registration path.
+2. Choose the **spine axis** — the single most consequential decision: organize the body by
+   **modality** (e.g. 2D → 3D), by **task** (generation / QA / deployment), or by
+   **lifecycle stage**. Every body section then follows this one axis; mixing axes is the
+   most common structural failure.
+3. Require a **scope statement + non-overlap boundary** against prior/adjacent reviews — this
+   pre-empts the reviewer's first question, "why another review on this?" (user-approval
+   checkpoint: confirm the boundary with the user before scaffolding).
+
+## Step 1 — Scaffold the 7-part macro skeleton
+
+Load `${CLAUDE_SKILL_DIR}/references/macro_skeleton.md` and instantiate:
+
+1. **Abstract** — structured for scoping/systematic; a 4-5 move version for narrative.
+2. **Introduction** — clinical motivation → technology → **scope + non-overlap block
+   (required field)** → "this review…".
+3. **Background / technical principles** — tight; cite once, do not re-survey the field.
+4. **Thematic body by spine axis** — each section ends with a **summary table** (stub
+   generated to match the type, Step 2).
+5. **Frontiers / what is advancing.**
+6. **Challenges / discussion** — include an **evaluation-metrics critique subsection** (a
+   required quality signal: how the field measures itself, and where those metrics mislead).
+7. **Conclusion** — measured; no recommendation-grade language for a scoping review.
+
+## Step 2 — Summary-table stub (matched to type)
+
+- Narrative / scoping: `study | year | [spine-axis value] | method | key finding`.
+- Systematic: PRISMA flow + a study-characteristics table + an extraction table.
+
+The stub ships with column headers and one placeholder row; rows are filled only from
+verified sources (see Anti-Hallucination).
+
+## Step 3 — Reporting + registration wiring
+
+- **Scoping** → PRISMA-ScR (+ JBI charting) + OSF registration.
+- **Narrative** → SANRA (a 6-item appraisal aid, not a reporting checklist — do not
+  over-enforce it).
+- **Systematic** → PRISMA 2020 (+ PROSPERO registration).
+- If `/check-reporting` does not yet carry the chosen checklist (e.g. PRISMA-ScR), track a
+  manual gap table and flag it for the user rather than silently skipping the item.
+
+## Step 4 — QC hand-off
+
+Run the standard manuscript QC chain, which this skill is designed to feed:
+
+1. `/self-review` — the RV1-RV8 narrative-review probes auto-activate for a review article.
+2. `/check-reporting` — the chosen guideline (SANRA / PRISMA-ScR / PRISMA 2020).
+3. `/verify-refs` — every citation resolves; 0 FABRICATED / MISMATCH.
+4. `/humanize` — AI-pattern density below threshold.
+5. `/academic-aio` — discoverability pass (optional).
+
+**Convergence gate:** self-review fatal = 0; verify-refs FABRICATED/MISMATCH = 0; no
+`[NEEDS-REF]` / `[@NEW:]`-style placeholder citations remain; humanize density < 2.0.
+
+## Guards
+
+- Citations resolve to `_src/refs.bib` only; never invent citekeys (see Anti-Hallucination).
+- Proportionate self-citation; declare an intellectual conflict of interest when an author
+  has contributed to the area being reviewed (per `intellectual-coi`).
+- Write only inside the manuscript directory.
+
+## references/
+
+- `macro_skeleton.md` — the 7-part template and the table/figure plan per review type.

package/skills/review-paper/references/macro_skeleton.md

@@ -0,0 +1,6 @@
+# Review macro skeleton (7-part) — reference template
+1. Abstract  2. Introduction (scope + non-overlap)  3. Background
+4. Thematic body by spine axis (+ summary table per section)
+5. Frontiers  6. Challenges/Discussion (+ evaluation-metrics critique)  7. Conclusion
+Tables: model-comparison (narrative/scoping) or PRISMA flow + extraction (systematic).
+Figures: conceptual schematic; landscape/timeline; PRISMA(-ScR) flow.

package/skills/review-paper/skill.yml

@@ -0,0 +1,25 @@
+schema_version: 2
+name: review-paper
+layer: C
+owner_domain: manuscript_authoring
+
+when_to_use: "Scaffold and draft a literature review (narrative / scoping / systematic) for medical/AI research, organized around an explicit spine axis with a non-overlap boundary and reporting-guideline wiring."
+when_NOT_to_use: "Original research articles, case reports, meta-analyses with pooled synthesis (use write-paper / meta-analysis). Pre-protocol topic discovery (use ma-scout)."
+
+inputs:
+  - "topic + chosen format (narrative/scoping/systematic)"
+  - "verified refs (_src/refs.bib) from search-lit/lit-sync"
+  - "optional: prior/adjacent reviews to differentiate against"
+outputs:
+  - "manuscript.md scaffold (7-part) + summary-table stub + figure/table legend plan"
+side_effects:
+  - writes_manuscript_scaffold
+downstream_consumers:
+  - self-review
+  - check-reporting
+  - humanize
+  - academic-aio
+  - manage-refs
+forbidden_actions:
+  - invent_citations
+  - write_outside_manuscript_dir