medsci-skills 4.1.0

package/skills/make-figures/scripts/validate_pptx_mac_compat.py

@@ -0,0 +1,233 @@
+#!/usr/bin/env python3
+"""Validate a .pptx for Mac PowerPoint compatibility.
+
+Detects four classes of defect that PowerPoint Mac renders differently
+from PowerPoint Windows / Keynote / LibreOffice and that PDF export
+alone does not catch:
+
+1. TIFF images embedded in ppt/media/ — Mac PowerPoint silently drops them.
+2. <a:sp3d> 3-D bevel inside text rPr — Mac renders as red outline that
+   does not appear in PDF or on Windows.
+3. docProps/app.xml count mismatch with actual slide count — triggers a
+   "PowerPoint found a problem" recovery dialog on first open.
+4. <a:srcRect> values exceeding 100000 (1/1000-percent) — image is
+   over-cropped (sometimes 99 % cut off) only on Mac.
+
+Reference rule: ~/.claude/rules/pptx-mac-compatibility.md.
+
+Usage:
+    python validate_pptx_mac_compat.py path/to/deck.pptx
+    python validate_pptx_mac_compat.py deck.pptx --json out.json
+    python validate_pptx_mac_compat.py deck.pptx --strict   # exit 1 on any FAIL
+
+Exit codes:
+    0 — all checks PASS
+    1 — at least one FAIL (only with --strict; otherwise still 0 with WARN)
+    2 — input invalid (file missing, not a zip, etc.)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+import zipfile
+from pathlib import Path
+
+
+SP3D_RE = re.compile(r"<a:sp3d\b", re.IGNORECASE)
+SRC_RECT_RE = re.compile(
+    r'<a:srcRect\b[^/>]*?(?:l|t|r|b)="(\d+)"', re.IGNORECASE
+)
+APP_XML_SLIDES_RE = re.compile(r"<Slides>(\d+)</Slides>", re.IGNORECASE)
+APP_XML_VECTOR_SIZE_RE = re.compile(
+    r'<vt:vector\b[^>]*?size="(\d+)"', re.IGNORECASE
+)
+
+
+def _check_tiff(zf: zipfile.ZipFile) -> list[str]:
+    found = [
+        name
+        for name in zf.namelist()
+        if name.lower().startswith("ppt/media/")
+        and name.lower().endswith((".tif", ".tiff"))
+    ]
+    return found
+
+
+def _check_sp3d(zf: zipfile.ZipFile) -> list[tuple[str, int]]:
+    hits: list[tuple[str, int]] = []
+    for name in zf.namelist():
+        if not (name.startswith("ppt/slides/") and name.endswith(".xml")):
+            continue
+        try:
+            text = zf.read(name).decode("utf-8", errors="replace")
+        except Exception:
+            continue
+        count = len(SP3D_RE.findall(text))
+        if count > 0:
+            hits.append((name, count))
+    return hits
+
+
+def _check_app_xml(zf: zipfile.ZipFile) -> dict:
+    result = {"present": False, "declared_slides": None, "actual_slides": None,
+              "vector_size_max": None, "mismatch": False}
+    actual = sum(
+        1
+        for n in zf.namelist()
+        if n.startswith("ppt/slides/slide") and n.endswith(".xml")
+    )
+    result["actual_slides"] = actual
+    try:
+        app = zf.read("docProps/app.xml").decode("utf-8", errors="replace")
+    except KeyError:
+        return result
+    result["present"] = True
+    m = APP_XML_SLIDES_RE.search(app)
+    if m:
+        declared = int(m.group(1))
+        result["declared_slides"] = declared
+        if declared != actual:
+            result["mismatch"] = True
+    sizes = [int(s) for s in APP_XML_VECTOR_SIZE_RE.findall(app)]
+    if sizes:
+        result["vector_size_max"] = max(sizes)
+    return result
+
+
+def _check_src_rect(zf: zipfile.ZipFile) -> list[tuple[str, int]]:
+    """Return [(slide_path, max_value)] for any srcRect value > 100000.
+
+    srcRect uses 1/1000-percent units; legitimate values are 0–100000.
+    Anything above 100000 indicates a unit-conversion bug (e.g., a
+    percent-to-1/1000-percent miscalculation) and produces severe over-crop
+    on Mac PowerPoint.
+    """
+    hits: list[tuple[str, int]] = []
+    for name in zf.namelist():
+        if not (name.startswith("ppt/slides/") and name.endswith(".xml")):
+            continue
+        try:
+            text = zf.read(name).decode("utf-8", errors="replace")
+        except Exception:
+            continue
+        values = [int(v) for v in SRC_RECT_RE.findall(text)]
+        bad = [v for v in values if v > 100000]
+        if bad:
+            hits.append((name, max(bad)))
+    return hits
+
+
+def validate(pptx_path: Path) -> dict:
+    if not pptx_path.exists():
+        return {"ok": False, "error": f"file not found: {pptx_path}"}
+    if not zipfile.is_zipfile(pptx_path):
+        return {"ok": False, "error": f"not a zip / pptx: {pptx_path}"}
+
+    with zipfile.ZipFile(pptx_path) as zf:
+        tiffs = _check_tiff(zf)
+        sp3d = _check_sp3d(zf)
+        app = _check_app_xml(zf)
+        srcrect = _check_src_rect(zf)
+
+    findings: list[dict] = []
+
+    if tiffs:
+        findings.append({
+            "id": "TIFF",
+            "severity": "FAIL",
+            "message": f"{len(tiffs)} TIFF image(s) embedded; Mac PowerPoint will silently drop these.",
+            "files": tiffs,
+            "fix": "Convert each to PNG (`sips -s format png in.tif --out out.png` on macOS) and update _rels/*.rels to reference the new .png filenames.",
+        })
+
+    if sp3d:
+        total = sum(c for _, c in sp3d)
+        findings.append({
+            "id": "SP3D",
+            "severity": "FAIL",
+            "message": f"<a:sp3d> 3-D bevel found in {len(sp3d)} slide(s) ({total} occurrence(s)); renders as red outline on Mac PowerPoint and is invisible in PDF export.",
+            "files": [{"slide": n, "count": c} for n, c in sp3d],
+            "fix": "Strip <a:sp3d>...</a:sp3d> blocks via regex in each slide XML. Verify on Mac PowerPoint after fix.",
+        })
+
+    if app["present"] and app["mismatch"]:
+        findings.append({
+            "id": "APP_XML_COUNT",
+            "severity": "FAIL",
+            "message": f"docProps/app.xml declares <Slides>{app['declared_slides']}</Slides> but the package contains {app['actual_slides']} slide XML files; PowerPoint Mac will show a 'recover file' dialog on first open.",
+            "fix": "Update <Slides>, <HeadingPairs>, and <TitlesOfParts> in docProps/app.xml to match the actual slide count.",
+        })
+    elif not app["present"]:
+        findings.append({
+            "id": "APP_XML_MISSING",
+            "severity": "WARN",
+            "message": "docProps/app.xml not found in package; PowerPoint Mac may show a recovery dialog or open with broken metadata.",
+            "fix": "Re-export the deck from PowerPoint (which writes app.xml) or generate one programmatically.",
+        })
+
+    if srcrect:
+        findings.append({
+            "id": "SRC_RECT_OVERFLOW",
+            "severity": "FAIL",
+            "message": f"<a:srcRect> values >100000 (1/1000-percent maximum) found in {len(srcrect)} slide(s); image will be over-cropped on Mac PowerPoint (often >99 % cut off).",
+            "files": [{"slide": n, "max_value": v} for n, v in srcrect],
+            "fix": "Recompute srcRect: percentages stay 0–100; 1/1000-percent units stay 0–100000. Compare to original .pptx srcRect values if a build script regressed.",
+        })
+
+    fail_count = sum(1 for f in findings if f["severity"] == "FAIL")
+    warn_count = sum(1 for f in findings if f["severity"] == "WARN")
+
+    return {
+        "ok": fail_count == 0,
+        "file": str(pptx_path),
+        "summary": {
+            "fail": fail_count,
+            "warn": warn_count,
+            "slides": app["actual_slides"],
+        },
+        "findings": findings,
+    }
+
+
+def _format_human(report: dict) -> str:
+    if not report.get("ok") and "error" in report:
+        return f"ERROR: {report['error']}"
+    lines = [f"PPTX Mac compatibility check — {report['file']}"]
+    s = report["summary"]
+    lines.append(f"  slides={s['slides']}  fail={s['fail']}  warn={s['warn']}")
+    if not report["findings"]:
+        lines.append("  ✓ All four checks PASS (TIFF, sp3d, app.xml count, srcRect).")
+        return "\n".join(lines)
+    for f in report["findings"]:
+        lines.append(f"  [{f['severity']}] {f['id']}: {f['message']}")
+        lines.append(f"        fix: {f['fix']}")
+    return "\n".join(lines)
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    ap.add_argument("pptx", help="path to .pptx")
+    ap.add_argument("--json", help="write JSON report to this path")
+    ap.add_argument("--strict", action="store_true",
+                    help="exit 1 if any FAIL (default exits 0 with WARN)")
+    args = ap.parse_args(argv)
+
+    report = validate(Path(args.pptx))
+    if not report.get("ok") and "error" in report:
+        print(_format_human(report), file=sys.stderr)
+        return 2
+
+    if args.json:
+        Path(args.json).write_text(json.dumps(report, indent=2))
+    print(_format_human(report))
+
+    if args.strict and not report["ok"]:
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/make-figures/skill.yml

@@ -0,0 +1,52 @@
+schema_version: 2
+name: make-figures
+version: 1.1.0
+layer: B
+owner_domain: figure_generation
+when_to_use:
+  - User requests a figure, plot, diagram, or visual abstract for a medical research manuscript
+  - Triggered by /write-paper Phase 5 (figure generation step)
+  - Following /analyze-stats output that requires visualization
+  - Generating PRISMA / CONSORT / STARD / STROBE flow diagrams
+  - Producing journal-specific visual or graphical abstracts
+when_NOT_to_use:
+  - Self-contained tabular results (use /analyze-stats markdown output)
+  - Decorative slides for talks (use /present-paper)
+  - Logos, branding, or non-research illustrations (out of scope)
+  - AI-generated images for journals that prohibit them (JACC family, NEJM) — see Journal AI-Image Policies in SKILL.md
+inputs:
+  - analysis/_analysis_outputs.md
+  - analysis/tables/*.csv
+outputs:
+  - analysis/figures/_figure_manifest.md
+  - analysis/figures/*.png
+  - analysis/figures/*.pdf
+deterministic_scripts:
+  - scripts/generate_flow_diagram.R
+  - scripts/critic_figure.py
+  - scripts/generate_visual_abstract.py
+  - scripts/validate_pptx_mac_compat.py
+side_effects:
+  - writes_figure_artifacts
+  - reads_medical_illustration_assets_from_servier_or_bioart
+downstream_consumers:
+  - write-paper
+  - sync-submission
+  - present-paper
+forbidden_actions:
+  - fabricate_figure_numbers
+  - create_flow_diagrams_without_source_counts
+  - generate_AI_images_for_prohibited_targets
+
+# v2.1 quality card
+purpose: "Generate publication-ready figures and visual/graphical abstracts (ROC, forest, CONSORT/STARD/PRISMA flow, KM, Bland-Altman, etc.)."
+safety_boundaries:
+  - "Figure numbers are not fabricated; flow diagrams are built from real source counts."
+  - "Honors journal AI-image policies; no AI images for prohibited targets."
+known_limitations:
+  - "Figure correctness depends on correct input data/counts supplied by upstream skills."
+  - "PPTX visual abstracts need the Mac-compatibility check before sharing."
+validation_commands:
+  - "Rscript scripts/generate_flow_diagram.R"
+  - "python3 scripts/validate_pptx_mac_compat.py <file>"
+evidence_surface: demo

package/skills/make-figures/templates/official/NOTES.md

@@ -0,0 +1,62 @@
+# Official Reporting Guideline Templates
+
+This directory ships canonical flow diagram and figure templates for the four
+most commonly required reporting guidelines in clinical research:
+
+| Guideline | Source | What we ship | Why |
+|-----------|--------|--------------|-----|
+| PRISMA 2020 | prismastatement.org (CC-BY 4.0) | Locally built `.pptx` (4 variants: new/updated × v1/v2) | Site uses Squarespace JS-fingerprint redirect that blocks programmatic download. We reproduce the published layout (Page MJ et al. *BMJ* 2021;372:n71, Fig 1) and supply a `fill_prisma_template.py` to populate counts. |
+| CONSORT 2025 | consort-spirit.org | Official `.docx` (flow diagram + editable checklist) | Direct fetch works; supersedes CONSORT 2010 per the SPIRIT-CONSORT 2025 update. |
+| STARD 2015 | equator-network.org | Official `.pdf` flow diagram + `.docx` checklist | Flow diagram is published as PDF only; no Word source exists upstream. |
+| SPIRIT 2025 | consort-spirit.org | Official `.docx` (participant timeline + editable checklist) | Direct fetch works; supersedes SPIRIT 2013 per the 2025 update. |
+
+## Refresh / verify
+
+```bash
+bash scripts/fetch_official_templates.sh           # all targets
+bash scripts/fetch_official_templates.sh consort2010
+FORCE=1 bash scripts/fetch_official_templates.sh   # ignore cache
+```
+
+The fetcher reports per-target OK/SKIP/FAIL. URLs are versioned in the script
+header — if a target rotates, update `TARGETS=` and rerun.
+
+## PRISMA 2020 build/fill workflow
+
+```bash
+# (one-time) generate template variants
+python3 scripts/build_prisma2020_template.py --variant new \
+    --out templates/official/prisma2020/PRISMA_2020_flow_new_v1.pptx
+python3 scripts/build_prisma2020_template.py --variant new --include-other-sources \
+    --out templates/official/prisma2020/PRISMA_2020_flow_new_v2.pptx
+
+# fill with study counts (positional 10-tuple)
+python3 scripts/fill_prisma_template.py \
+    --template templates/official/prisma2020/PRISMA_2020_flow_new_v1.pptx \
+    --counts "315,122,186,7,111,204,102,84,3,15" \
+    --out fig1_prisma_filled.pptx
+
+# or with a JSON file giving every key
+python3 scripts/fill_prisma_template.py \
+    --template templates/official/prisma2020/PRISMA_2020_flow_new_v1.pptx \
+    --counts-file my_counts.json \
+    --out fig1_prisma_filled.pptx
+```
+
+Render to PDF/PNG via LibreOffice headless:
+
+```bash
+soffice --headless --convert-to pdf fig1_prisma_filled.pptx
+soffice --headless --convert-to png fig1_prisma_filled.pptx
+```
+
+## Attribution
+
+PRISMA layout: Page MJ, McKenzie JE, Bossuyt PM, et al. The PRISMA 2020
+statement: an updated guideline for reporting systematic reviews. *BMJ*
+2021;372:n71. doi:10.1136/bmj.n71. CC-BY 4.0.
+
+CONSORT 2025 / SPIRIT 2025: see https://www.consort-spirit.org/.
+
+STARD 2015: Bossuyt PM, Reitsma JB, Bruns DE, et al. STARD 2015. *BMJ*
+2015;351:h5527.

package/skills/make-figures/tests/fixtures/figure1_flow.yaml

@@ -0,0 +1,8 @@
+# STROBE flow config (SSOT) consumed by generate_flow_diagram.R
+boxes:
+  - id: assessed
+    label: "Assessed for eligibility (n = 1284)"
+  - id: excluded
+    label: "Excluded (n = 286)"
+  - id: analytic
+    label: "Analytic cohort (n = 998)"

package/skills/make-figures/tests/fixtures/manuscript_ok.md

@@ -0,0 +1,9 @@
+## Results
+The analytic cohort comprised 998 participants.
+
+## Figure Legends
+
+**Figure 1.** STROBE flow diagram. Of n = 1,284 assessed for eligibility, n = 286 were
+excluded, leaving an analytic cohort of n = 998.
+
+## References

package/skills/make-figures/tests/fixtures/manuscript_stale.md

@@ -0,0 +1,4 @@
+## Figure Legends
+
+**Figure 1.** STROBE flow diagram. Of n = 1,284 assessed for eligibility, n = 286 were
+excluded, leaving an analytic cohort of n = 1,150.

package/skills/make-figures/tests/test_legend_reconcile.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# Regression test for the Figure 1 caption ↔ flow-SSOT reconciler.
+# Synthetic fixtures: a flow config with counts {1284, 286, 998}; an OK caption
+# that matches, and a stale caption citing 1,150 (absent from the diagram).
+# Stdlib-only (python3).
+set -u
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SCRIPT="$HERE/../scripts/derive_figure_legend_counts.py"
+FLOW="$HERE/fixtures/figure1_flow.yaml"
+OK="$HERE/fixtures/manuscript_ok.md"
+STALE="$HERE/fixtures/manuscript_stale.md"
+OUT="$(mktemp -t fl_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
+}
+
+[[ -f "$SCRIPT" ]] || { echo "ENV-ERR: script missing" >&2; exit 2; }
+
+python3 "$SCRIPT" --flow-config "$FLOW" --manuscript "$OK" --strict >/dev/null 2>&1
+check "exit 0 when caption matches the flow SSOT" test "$?" -eq 0
+
+python3 "$SCRIPT" --flow-config "$FLOW" --manuscript "$STALE" --out "$OUT" --strict >/dev/null 2>&1
+check "exit 1 when caption cites a count absent from the flow SSOT" test "$?" -eq 1
+check "stale count 1150 flagged" python3 -c "
+import json; d=json.load(open('$OUT'))
+assert 1150 in d['stale_in_caption'], d['stale_in_caption']"
+check "verdict MISMATCH" python3 -c "
+import json; assert json.load(open('$OUT'))['verdict']=='MISMATCH'"
+
+echo "fail=$fail"; [[ "$fail" -eq 0 ]] && echo "ALL PASS" || echo "FAILURES: $fail"
+exit "$fail"