medsci-skills 4.1.0

package/skills/check-reporting/tests/test_checklist_version.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# Test scripts/check_checklist_version.py — the A4b checklist-version staleness gate.
+# Synthetic, PII-free fixtures: a checklist targeting an older version / a changed
+# hash / a different file / no version metadata, vs an in-sync checklist.
+set -u
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SCRIPT="$HERE/../scripts/check_checklist_version.py"
+PASS=0
+FAIL=0
+ok()  { echo "  PASS: $1"; PASS=$((PASS+1)); }
+bad() { echo "  FAIL: $1"; FAIL=$((FAIL+1)); }
+
+WORK="$(mktemp -d)"
+trap 'rm -rf "$WORK"' EXIT
+
+# current manuscript (v8) + its sha256 (first 12)
+cat > "$WORK/manuscript_v8.md" <<'EOF'
+## Title
+A cohort study, version 8.
+EOF
+SHA=$(python3 -c "import hashlib;print(hashlib.sha256(open('$WORK/manuscript_v8.md','rb').read()).hexdigest()[:12])")
+
+mk_json() {  # file target_manuscript target_version source_sha256
+  cat > "$1" <<EOF
+{"check_reporting_version":"1.1","manuscript_title":"A cohort study",
+ "target_manuscript":"$2","target_version":"$3","source_sha256":"$4",
+ "guideline":"STROBE","total_items":22,"present":18}
+EOF
+}
+
+run() { python3 "$SCRIPT" "$@" 2>/dev/null; }
+
+# 1. in-sync checklist (same file/version/hash) -> exit 0
+mk_json "$WORK/ck_ok.json" "manuscript_v8.md" "v8" "$SHA"
+run --checklist "$WORK/ck_ok.json" --manuscript "$WORK/manuscript_v8.md" --quiet
+[ $? -eq 0 ] && ok "in-sync checklist passes" || bad "in-sync should pass"
+
+# 2. older target_version -> stale (exit 1)
+mk_json "$WORK/ck_oldver.json" "manuscript_v6.md" "v6" ""
+run --checklist "$WORK/ck_oldver.json" --manuscript "$WORK/manuscript_v8.md" --out "$WORK/r.json" --quiet
+[ $? -eq 1 ] && ok "older target_version -> exit 1" || bad "older version should fail"
+python3 -c "import json,sys;d=json.load(open('$WORK/r.json'));sys.exit(0 if d['findings'][0]['type']=='checklist_version_stale' else 1)" \
+  && ok "reports checklist_version_stale" || bad "wrong finding type for version"
+
+# 3. changed content hash (same version) -> stale
+mk_json "$WORK/ck_hash.json" "manuscript_v8.md" "v8" "deadbeef0000"
+run --checklist "$WORK/ck_hash.json" --manuscript "$WORK/manuscript_v8.md" --out "$WORK/r2.json" --quiet
+python3 -c "import json,sys;d=json.load(open('$WORK/r2.json'));sys.exit(0 if d['findings'][0]['type']=='checklist_content_stale' else 1)" \
+  && ok "changed hash -> checklist_content_stale" || bad "hash drift not detected"
+
+# 4. no version metadata (pre-v1.1) -> unverifiable (exit 1)
+echo '{"check_reporting_version":"1.0","guideline":"STROBE","present":18}' > "$WORK/ck_old.json"
+run --checklist "$WORK/ck_old.json" --manuscript "$WORK/manuscript_v8.md" --out "$WORK/r3.json" --quiet
+[ $? -eq 1 ] && ok "no version metadata -> exit 1" || bad "missing metadata should fail"
+python3 -c "import json,sys;d=json.load(open('$WORK/r3.json'));sys.exit(0 if d['findings'][0]['type']=='checklist_no_version_metadata' else 1)" \
+  && ok "reports checklist_no_version_metadata" || bad "wrong finding for missing metadata"
+
+# 5. markdown report with header fields (no JSON) -> parsed + stale
+cat > "$WORK/report_v6.md" <<'EOF'
+## Reporting Guideline Compliance Report
+Manuscript: A cohort study
+Target manuscript file: manuscript_v6.md
+Target version: v6
+Guideline: STROBE 2007
+EOF
+run --checklist "$WORK/report_v6.md" --manuscript "$WORK/manuscript_v8.md" --quiet
+[ $? -eq 1 ] && ok "markdown header (v6) flagged stale vs v8" || bad "markdown header not parsed"
+
+echo ""
+echo "test_checklist_version: $PASS passed, $FAIL failed"
+[ "$FAIL" -eq 0 ]

package/skills/check-reporting/tests/test_framework_naming.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+# Regression test for the framework-naming audit (check-reporting Step 4e).
+# Synthetic, PII-free fixtures reproduce: (a) an AI extension used without naming
+# or citing its base instrument (BASE_MISSING), (b) mixed +AI / -AI hyphenation for
+# one family (HYPHEN_MIX), (c) vague "adapted per recent guidance" wording
+# (VAGUE_GUIDANCE), (d) a self-coined "12-AI" item label (SELF_COINED_LABEL). The
+# clean fixture names and cites both base instrument and extension.
+# Stdlib-only (python3).
+set -u
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SCRIPT="$HERE/../scripts/check_framework_naming.py"
+BAD="$HERE/fixtures/framework_bad.md"
+CLEAN="$HERE/fixtures/framework_clean.md"
+OUT="$(mktemp -t fw_XXXX).json"
+trap 'rm -f "$OUT"' EXIT
+
+fail=0
+check() { local label="$1"; shift
+    if "$@" >/dev/null 2>&1; then printf '  PASS  %s\n' "$label"
+    else printf '  FAIL  %s\n' "$label"; fail=$((fail+1)); fi
+}
+has_verdict() { python3 -c "
+import json,sys
+d=json.load(open('$OUT'))
+assert any(c['verdict']=='$1' for c in d['claims']), '$1 not found'
+"; }
+
+[[ -f "$SCRIPT" ]] || { echo "ENV-ERR: script missing" >&2; exit 2; }
+
+# (1) bad manuscript: BASE_MISSING is Major -> exit 1 under --strict
+python3 "$SCRIPT" --manuscript "$BAD" --out "$OUT" --strict --quiet >/dev/null 2>&1
+check "exit 1 under --strict (Major present)" test "$?" -eq 1
+check "JSON artifact written" test -s "$OUT"
+check "BASE_MISSING detected (extension without base)" has_verdict BASE_MISSING
+check "HYPHEN_MIX detected (PROBAST+AI vs PROBAST-AI)"  has_verdict HYPHEN_MIX
+check "VAGUE_GUIDANCE detected (adapted per recent guidance)" has_verdict VAGUE_GUIDANCE
+check "SELF_COINED_LABEL detected (12-AI)" has_verdict SELF_COINED_LABEL
+
+# (2) clean manuscript: base named + cited, consistent hyphenation -> exit 0
+python3 "$SCRIPT" --manuscript "$CLEAN" --strict --quiet >/dev/null 2>&1
+check "exit 0 on clean manuscript (base named + cited)" test "$?" -eq 0
+
+echo "fail=$fail"; [[ "$fail" -eq 0 ]] && echo "ALL PASS" || echo "FAILURES: $fail"
+exit "$fail"

package/skills/check-reporting/tests/test_prisma_cascade.sh

@@ -0,0 +1,104 @@
+#!/usr/bin/env bash
+# Regression tests for check-reporting prisma_cascade_check.py.
+
+set -uo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/../../.." && pwd)"
+SCRIPT="$REPO_ROOT/skills/check-reporting/scripts/prisma_cascade_check.py"
+TMP="$(mktemp -d -t prisma_cas.XXXXXX)"
+trap 'rm -rf "$TMP"' EXIT
+
+[[ -f "$SCRIPT" ]] || { echo "ENV-ERR: script missing" >&2; exit 2; }
+
+fail=0
+ran=0
+assert_exit() {
+    local label="$1" expected="$2" actual="$3"
+    ran=$((ran + 1))
+    if [[ "$expected" == "$actual" ]]; then
+        printf '  PASS  %-50s exit=%s\n' "$label" "$actual"
+    else
+        printf '  FAIL  %-50s expected=%s actual=%s\n' "$label" "$expected" "$actual"
+        fail=$((fail + 1))
+    fi
+}
+
+build_tsv() {
+    local out="$1" col="$2"
+    shift 2
+    {
+        printf 'uid\t%s\n' "$col"
+        local i=1
+        for label in "$@"; do
+            printf 'UID_%03d\t%s\n' "$i" "$label"
+            i=$((i + 1))
+        done
+    } > "$out"
+}
+
+# --------------------------------------------------------------------------
+# Case 1: matching counts (no manuscript) => PASS.
+# round 1: 5 INCLUDE, 5 EXCLUDE
+# round 2: 3 INCLUDE, 2 EXCLUDE
+# round 3: 2 INCLUDE, 1 EXCLUDE
+# --------------------------------------------------------------------------
+build_tsv "$TMP/c1_r1.tsv" decision INCLUDE INCLUDE INCLUDE INCLUDE INCLUDE EXCLUDE EXCLUDE EXCLUDE EXCLUDE EXCLUDE
+build_tsv "$TMP/c1_r2.tsv" decision INCLUDE INCLUDE INCLUDE EXCLUDE EXCLUDE
+build_tsv "$TMP/c1_r3.tsv" round3_decision INCLUDE INCLUDE EXCLUDE
+python3 "$SCRIPT" --round1 "$TMP/c1_r1.tsv" --round2 "$TMP/c1_r2.tsv" \
+    --round3 "$TMP/c1_r3.tsv" --out "$TMP/c1.json" --quiet
+assert_exit "case 1: TSV only, no manuscript (PASS)" 0 $?
+python3 - "$TMP/c1.json" <<'PY' || fail=$((fail + 1))
+import json, sys
+r = json.load(open(sys.argv[1]))
+sc = r["stage_counts"]
+assert sc["round1_total"] == 10, sc
+assert sc["round1_include"] == 5, sc
+assert sc["round3_include"] == 2, sc
+PY
+
+# --------------------------------------------------------------------------
+# Case 2: manuscript claims correct count => PASS.
+# --------------------------------------------------------------------------
+cat > "$TMP/c2_manuscript.md" <<'EOF'
+## **METHODS**
+After title and abstract screening, 3 records were retrieved for full-text review.
+Finally included 2 studies in the meta-analysis.
+EOF
+python3 "$SCRIPT" --round1 "$TMP/c1_r1.tsv" --round2 "$TMP/c1_r2.tsv" \
+    --round3 "$TMP/c1_r3.tsv" \
+    --manuscript "$TMP/c2_manuscript.md" \
+    --out "$TMP/c2.json" --quiet
+assert_exit "case 2: manuscript matches (PASS)" 0 $?
+
+# --------------------------------------------------------------------------
+# Case 3: manuscript prose off-by-one => FAIL.
+# Computed round3_include = 2; manuscript says "3 studies"
+# --------------------------------------------------------------------------
+cat > "$TMP/c3_manuscript.md" <<'EOF'
+## **RESULTS**
+Finally included 3 studies in the meta-analysis.
+EOF
+python3 "$SCRIPT" --round1 "$TMP/c1_r1.tsv" --round2 "$TMP/c1_r2.tsv" \
+    --round3 "$TMP/c1_r3.tsv" \
+    --manuscript "$TMP/c3_manuscript.md" \
+    --out "$TMP/c3.json" --quiet
+assert_exit "case 3: off-by-one prose drift (FAIL)" 1 $?
+python3 - "$TMP/c3.json" <<'PY' || fail=$((fail + 1))
+import json, sys
+r = json.load(open(sys.argv[1]))
+drifts = r["manuscript_drift"]
+assert any(d["stage"] == "round3_include" and d["manuscript"] == 3 for d in drifts), drifts
+PY
+
+# --------------------------------------------------------------------------
+# Case 4: bad column => exit 2.
+# --------------------------------------------------------------------------
+build_tsv "$TMP/c4.tsv" notes INCLUDE EXCLUDE
+python3 "$SCRIPT" --round1 "$TMP/c4.tsv" --round2 "$TMP/c1_r2.tsv" \
+    --round3 "$TMP/c1_r3.tsv" --out "$TMP/c4.json" --quiet 2>/dev/null
+assert_exit "case 4: bad column (exit 2)" 2 $?
+
+echo ""
+echo "ran=$ran fail=$fail"
+[[ $fail -eq 0 ]]

package/skills/clean-data/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: clean-data
+description: Interactive data profiling and cleaning assistant for medical research. Three-stage workflow (profile, flag, code-generate) with user approval gates at each step. Handles missing values, outliers, duplicates, and type mismatches in CSV/Excel clinical data. Does NOT auto-clean — all decisions require researcher confirmation.
+triggers: clean data, data cleaning, data preprocessing, data profiling, missing values, outliers, check my data, data quality
+tools: Read, Write, Edit, Bash, Grep, Glob
+model: inherit
+---
+
+# Data Profiling and Cleaning Skill
+
+You are assisting a medical researcher with data profiling and cleaning for clinical datasets.
+This is a three-stage interactive workflow. You generate code and reports -- you do NOT
+auto-clean data. Every cleaning decision requires explicit researcher confirmation.
+
+## Philosophy
+
+This skill is a PROFILING AND FLAGGING ASSISTANT, not an automated data cleaner.
+Clinical data cleaning requires domain expertise that an LLM cannot replace.
+Every cleaning decision must be confirmed by the researcher.
+
+**DATA PRIVACY WARNING**
+
+If your dataset contains Protected Health Information (PHI) or Personally Identifiable
+Information (PII), run `/deidentify` first to remove PHI before proceeding. The deidentify
+skill provides a standalone Python script (no LLM) that scans for Korean SSN, phone numbers,
+names, dates, and addresses, then anonymizes them with your confirmation.
+
+If `*_deidentified.*` files exist in the working directory, use those instead of raw data.
+
+Alternatively:
+1. Provide only the data dictionary / codebook for profiling guidance
+2. Or use a local-only environment with no network access
+
+This tool generates CODE that runs on your data -- it does not need to see the raw data
+to generate useful profiling scripts.
+
+## Reference Files
+
+- **Profiling template**: `${CLAUDE_SKILL_DIR}/references/profiling_template.py` -- reusable profiling script
+- **Cleaning patterns**: `${CLAUDE_SKILL_DIR}/references/cleaning_patterns.md` -- common clinical data patterns
+
+Read relevant references before generating profiling or cleaning code.
+
+## Three-Stage Workflow
+
+### Stage 1: Profiling
+
+**Input**: CSV/Excel file path OR data dictionary/codebook
+
+**Actions**:
+
+1. Generate a Python profiling script (pandas-based) that produces:
+   - Variable count, row count, data types
+   - Missing value count and percentage per variable
+   - Unique value counts for categorical variables
+   - Min/max/mean/median/SD for numeric variables
+   - Distribution plots (histograms for numeric, bar charts for categorical)
+2. If user provides a codebook: cross-reference variable names, expected types, expected ranges
+3. Present summary table to user
+
+Use `${CLAUDE_SKILL_DIR}/references/profiling_template.py` as the base script. Adapt it to
+the specific dataset structure.
+
+**Gate**: User reviews profiling output before proceeding. Ask:
+> "Here is the profiling summary. Would you like to proceed to Stage 2 (Flagging)?
+> Are there any variables you want to exclude or focus on?"
+
+### Stage 2: Flagging
+
+Based on profiling results, flag potential issues in these categories:
+
+1. **Missing values**: Variables with >5% missing, pattern analysis (MCAR/MAR/MNAR heuristic)
+2. **Statistical outliers**: IQR method (Q1 - 1.5*IQR, Q3 + 1.5*IQR) and Z-score (|z| > 3)
+3. **Duplicates**: Exact row duplicates AND near-duplicates (same patient ID, different dates)
+4. **Type mismatches**: Numeric stored as string, dates in inconsistent formats
+5. **Implausible values**: ONLY if codebook provides valid ranges; otherwise flag as "review needed"
+6. **Category inconsistencies**: Typos in categorical values (e.g., "Male", "male", "M", "MALE")
+7. **Categorical-implied zeros**: When a categorical variable defines a natural zero for a dose/duration variable (`smoking_status == 'never'` implies `pack_years == 0`, `alcohol_use == 'never'` implies `grams_per_week == 0`), flag any record where the implied zero is stored as NULL/missing instead of 0. This is a *contradiction*, not a missing-data pattern: a never-smoker with `pack_years = NULL` will be silently dropped by complete-case models or, worse, imputed to a non-zero dose by MICE — corrupting the exposure contrast. Suggested action: "Set dose = 0 where category == reference level; impute only the residual missingness among the exposed." Detected by `scripts/check_structural_zero.py` given the category↔dose mapping; pairs with `/analyze-stats` "Covariate Pitfalls: Structural Zeros & Dose/Duration Variables".
+
+Present the flag report as a structured table:
+
+| Variable | Issue Type | Count | Severity | Suggested Action |
+|----------|-----------|-------|----------|-----------------|
+| age | Outlier (IQR) | 3 | Medium | Review: values 150, 200, -5 |
+| sex | Category inconsistency | 12 | Low | Harmonize: Male/male/M -> "Male" |
+| lab_date | Type mismatch | 45 | High | Parse to datetime |
+| pack_years | Categorical-implied zero | 12421 | High | Set 0 where smoking_status=='never' (structural zero, not missing) |
+
+Severity levels:
+- **High**: Likely data errors that will affect analysis (type mismatches, impossible values)
+- **Medium**: Potential issues that need expert review (statistical outliers, moderate missingness)
+- **Low**: Minor inconsistencies that are easy to fix (category labels, trailing whitespace)
+
+**Gate**: User reviews flags and approves/rejects each suggested action. Ask:
+> "Please review the flagged issues above. For each row, indicate:
+> (A) Approve the suggested action, (R) Reject / keep as-is, or (M) Modify the action.
+> Only approved actions will generate cleaning code."
+
+### Stage 3: Code Generation
+
+For ONLY user-approved cleaning actions, generate Python (or R if requested) code:
+
+- **Missing value handling**: Listwise deletion, mean/median imputation, or MICE setup (code only, user runs)
+- **Outlier handling**: Winsorization, removal, or keep-and-flag
+- **Duplicate removal**: Exact dedup with logging
+- **Type conversion**: Standardize dates, numeric parsing
+- **Category harmonization**: Mapping table for inconsistent labels
+
+All generated code MUST include:
+- Before/after row counts printed to console
+- Logging of every modification to a cleaning log DataFrame
+- Reproducibility: `np.random.seed(42)` and `random.seed(42)` where applicable
+- Output: cleaned CSV + `cleaning_log.csv`
+- Clear comments explaining each cleaning step
+
+End the generated script with this notice:
+> "This code implements ONLY the cleaning rules you approved. Review the cleaning_log.csv
+> output to verify all changes before proceeding to analysis."
+
+## Scope Limitations
+
+**Supported**:
+- Missing values (detection, simple imputation code, MICE setup)
+- Outliers (statistical detection via IQR and Z-score)
+- Duplicates (exact and near-duplicate detection)
+- Type mismatches (numeric parsing, date standardization)
+- Category harmonization (case, abbreviation, whitespace)
+
+**NOT supported**:
+- Domain-specific plausible ranges (unless codebook provided)
+- Complex imputation strategy selection (MICE setup only, user picks variables/method)
+- Natural language extraction from clinical notes
+- Image data cleaning or DICOM metadata
+- Automated decisions -- all cleaning requires researcher approval
+
+> This tool flags issues. Final cleaning decisions require your domain knowledge.
+
+## Cross-Skill Integration
+
+- **clean-data** sits BEFORE `analyze-stats` in the research pipeline
+- `design-study` can inform which variables to focus profiling on
+- `manage-project` tracks overall project state including data cleaning status
+- After cleaning, hand off to `analyze-stats` for statistical analysis
+
+## Output Format
+
+Structure all reports using this template:
+
+```
+## Data Profiling Report
+
+### Dataset Overview
+- Rows: [N]
+- Columns: [N]
+- File size: [size]
+- Date range: [if applicable]
+
+### Variable Summary
+| Variable | Type | Missing N (%) | Unique | Min | Max | Mean | SD |
+|----------|------|---------------|--------|-----|-----|------|-----|
+| ...      | ...  | ...           | ...    | ... | ... | ...  | ... |
+
+### Flags
+| Variable | Issue | Count | Severity | Suggested Action |
+|----------|-------|-------|----------|-----------------|
+| ...      | ...   | ...   | ...      | ...             |
+
+### Cleaning Code
+[Python/R script -- only for approved actions]
+
+### Cleaning Log
+[What was changed, how many rows affected, before/after counts]
+```
+
+## 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.