git:20260922.492dd73 to git:20260930.30387c2

- description: Generate publication-ready figures and visual abstracts for medical research papers. Supports ROC curves, forest plots, CONSORT/STARD/PRISMA flow diagrams, calibration plots, Kaplan-Meier curves, Bland-Altman plots, confusion matrices, pipeline diagrams, and journal-specific visual/graphical abstracts (python-pptx template-based).

- triggers: figure, plot, graph, diagram, ROC curve, forest plot, flow diagram, CONSORT diagram, PRISMA flow, visualization, chart, visual abstract, graphical abstract, key message, figure design, figure planning, effective figure, cognitive load

- tools: Read, Write, Edit, Bash, Grep, Glob

- You are helping a medical researcher generate publication-ready figures for medical research

- manuscripts. Every figure must meet journal specifications for dimensions, resolution, fonts, and

- color accessibility. Produce clean, data-focused visuals with no chartjunk.

-

- ## Credits

-

- The Critic Loop (Step 4b) in this skill is inspired by PaperBanana (Zhu et al., *Automating

- Academic Illustration for AI Scientists*, arXiv:2601.23265, 2025) and by prior self-refinement

- research — Self-Refine (Madaan et al., 2023), Reflexion (Shinn et al., 2023), and Constitutional

- AI (Anthropic, 2022). This is a clean-room reconstruction specialized for medical publication

- figures (STARD / CONSORT / PRISMA, journal-specific specs, Wong colorblind palette). No code,

- prompts, or configurations are derived from PaperBanana's repository.

-

- ## Communication Rules

-

- - Communicate with the user in their preferred language.

- - All figure text (labels, legends, annotations) must be in English.

- - Medical terminology is always in English.

-

- 2. If only raw CSV/Excel files exist (no `*_deidentified.*` counterpart), warn the user (ask in the user's preferred language):

- > "Does this data contain patient identifiers (names, national ID / RRN, contact details, etc.)?

- > If so, please de-identify it first with the `/deidentify` skill."

- - **Figure specifications**: `${CLAUDE_SKILL_DIR}/references/figure_specs.md`

- - **Figure style**: `${CLAUDE_SKILL_DIR}/../analyze-stats/references/style/figure_style.mplstyle` (or project's CLAUDE.md if available)

- - **Project data**: See CLAUDE.md for data locations under `2_Data/`

-

- Read `figure_specs.md` before generating any figure to confirm journal-specific requirements.

- > Synced with the user's global rule `~/.claude/rules/journal-ai-image-policies.md`. The table below is the local copy used during autonomous workflow; the global rule is authoritative when conflicts arise.

-

-

- When a figure is produced by a data-driven `.py`/`.R` script (ROC, forest, KM, calibration, heat maps), lint that script before finalizing with the `/analyze-stats` code-quality gate (`check_generated_code.py {script} --strict`): it catches a missing plotting seed for any bootstrapped CI band, a hardcoded absolute data path, or a hand-typed data literal that should have been read from the analysis CSV.

-

- ### Decoration vs information

-

- Even when AI images are allowed, AI-generated illustrations are immediately recognizable to experienced reviewers (small decorative icons that add no information, overly uniform layouts, generic clip-art style). For high-impact submissions, prefer Servier / BioArt / BioRender + matplotlib overlays over AI.

-

- ---

- ## DPI and Resolution Guide

- | Output | Minimum DPI | Notes |

- |--------|------------|-------|

- | Journal halftone (photos, screenshots) | 300 | Standard for most journals |

- | Journal line art (diagrams, graphs) | 600 | Required by Radiology, most Elsevier journals |

- | Poster presentation | 150-200 | Lower is acceptable for large-format prints |

- | Screen/web only | 72-150 | Not for print submission |

- **Practical workflow for screen captures**:

- - Use HyperSnap or similar tool with DPI pre-set to the journal requirement

- - Compose the figure in PPT at high zoom → capture at target DPI → save as TIFF/PNG

- - Verify final file dimensions match journal column width requirements

- Many journals now require or strongly encourage visual abstracts. European Radiology made

- graphical abstracts mandatory for all Original Articles from first revision (Jan 2025).

- Submitting one voluntarily signals effort and can improve editorial impression.

-

- ### Journal Requirements

-

- | Status | Example Journals |

- |--------|-----------------|

- | **Mandatory** | European Radiology (from 1st revision, all Original Articles) |

- | **Encouraged** | Abdominal Radiology, JCO, Annals of Internal Medicine |

- | **Voluntary** | Most other journals — improves social media visibility |

-

- Check the target journal profile (`write-paper/references/journal_profiles/`) for specific

- visual abstract requirements before starting.

- 3. **Select visual element** (priority order — no API needed for top options):

- ### Design Principles

-

- - One page, landscape (16:9) or per journal template specification

- - Three sections: Study question → Key method → Main result

- - Use the study's actual figures rather than generic graphics

- - Minimize text — let visuals carry the message

- - Every visual element must serve a purpose (no decorative clip-art)

- **Using a journal's own template.** Several journals publish one — European Radiology requires a

- graphical abstract from first revision and supplies `EURA-GA-Jan2025.pptx`. We do not redistribute

- them: a template you may download is not a template we may ship. Use yours directly instead:

- A Central Illustration (CI) is **not** a Visual Abstract (VA). They serve different purposes and follow different rules. JACC family journals (JACC, JACC: Asia, JACC: Cardiovascular Imaging, JACC: Heart Failure, JACC: CardioOncology, JACC: Clinical Electrophysiology, JACC: Basic to Translational Science) require a Central Illustration with every Original Article. Reference: Fuster V, Mann DL. *JACC.* 2019;74(22):2816–2820.

-

- | Aspect | Central Illustration | Visual Abstract |

- |---|---|---|

- | Purpose | Single key finding / take-home message | Methods + Results pictorial summary |

- | Where in paper | End of Results / start of Discussion | Beginning of paper |

- | Methods content | **None** | Required |

- | Audience | Cardiovascular clinicians + journal-issue readers | Broad including non-specialists / social media |

- | Used by | All JACC family + JACC: Asia | Originally JACC: Basic to Translational Science |

- | Text density | Minimal (graphical priority) | More allowed (methods labels) |

- | Bar graphs | OK if they capture entire message | Avoid — use ↑↓ arrows |

- | Default complexity | 1–3 visual zones | Q→M→R three blocks |

-

- ### Fuster-Mann five rules (CI must pass all)

-

- 1. **Know the message.** One finding, not study design + multiple findings.

- 2. **Convey graphically, not textually.** Even a simple KM curve is OK.

- 3. **Avoid using too much text.** Replace with icons or arrows.

- 4. **Avoid secondary messages.** ≤ 5 seconds for a viewer to state the main finding.

- 5. **Simplicity is superior.** Default to fewer panels.

-

- Full guidance and validation thresholds: `${CLAUDE_SKILL_DIR}/references/jacc_central_illustration_principles.md`.

- CI mode validates before rendering and rejects (exit 2) if any of: zones > 3, label words > 30, numerical points > 4, or methodology terms (cohort flow / inclusion / exclusion / study design / enrollment / randomized / sample size / CONSORT / PRISMA / STARD) appear in `--ci-raw-text`. Override individual rules with `--ci-allow {zones|words|numerical|methods}` only when you have a defensible reason.

-

- The JACC submission PPTX is a 10×7.5 in slide with 4 placeholders (citation textbox, content picture, footer textbox reserved, JACC logo). The red border + blue "CENTRAL ILLUSTRATION:" header are applied by JACC editorial after acceptance — authors submit only the content figure + citation.

- (3) whether a figure is the right vehicle (vs a small table or in-line text). The

- five strategies in that file shift Step 1 from "which chart fits the data" to

- "what should the reader remember 10 seconds later." Skip only when the figure

- is mandated by a reporting guideline (e.g., PRISMA / CONSORT flow), and even

- then apply the cognitive-load checklist.

- `${CLAUDE_SKILL_DIR}/references/reporting_guideline_figure_map.md` — the

- 14-row table tells you which guideline mandates which figures and whether

- this skill ships an official template (✅), generic flow only (⚠️), or

- needs manual production (❌). Critical for AI-extension guidelines

- (CONSORT-AI, STARD-AI, TRIPOD+AI, CLAIM 2024, DECIDE-AI).

- **For medical AI / engineering pipeline figures** (DICOM workflow,

- annotation pipeline, federated learning topology, model architecture),

- also load `${CLAUDE_SKILL_DIR}/references/pipeline_concepts_medical_ai.md` —

- canonical layouts, required annotations, and tool selection per type.

- Ask the user for:

- 1. **Figure type** (from the supported types below) — skipped when `--study-type` is provided

- If the user provides enough context, infer missing parameters and confirm before proceeding.

-

- 1. Load the figure style file:

- ```python

- import matplotlib.pyplot as plt

- import os

- style_path = os.path.join(os.environ.get('CLAUDE_SKILL_DIR', '.'), '../analyze-stats/references/style/figure_style.mplstyle')

- if os.path.exists(style_path):

- plt.style.use(style_path)

- ```

- 2. Look up journal-specific dimensions from `${CLAUDE_SKILL_DIR}/references/figure_specs.md`.

- 4. Configure font sizes per element type (title, axis label, tick label, legend, annotation).

- Create the figure using Python (matplotlib/seaborn as primary, with specialized libraries as needed).

- ### Step 4: Review

- Present the figure to the user and ask:

- - Does the layout work?

- - Are labels and annotations correct?

- - Any adjustments to colors, sizing, or emphasis?

- Iterate until the user approves.

- Before Step 5 Export, run the automated Critic Loop. This is two stages —

- deterministic quantitative checks via Python, then qualitative review by

- Claude itself — and the combined output tells us whether to re-render or

- hand off to the user.

- --source-text figures/fig1_stard.txt \ # optional: expected strings for OCR coverage

- This produces a JSON report covering:

- - DPI and physical width vs. journal spec

- - Dominant-color breakdown and out-of-Wong-palette fraction

- - OCR-detected word count, minimum text height, and (if a source-text file

- was provided) source-word coverage

- **Stage 2: Qualitative review (Claude session)**

- 2. Read the corresponding rubric file:

- (sections A–G; section G adds cognitive-load and template-fidelity checks)

- - Data plots: `${CLAUDE_SKILL_DIR}/references/critic_rubrics/data_plot.md`

- (sections A–G; section G adds calibration / fairness / colorblind+redundant /

- dataset-flow / decision-curve checks for medical AI papers)

- - For PRISMA / CONSORT / STARD / STROBE specifically, also read

- `${CLAUDE_SKILL_DIR}/references/flow_diagram_lessons.md` — five

- production lessons covering official-template fidelity, PDF export

- fidelity (VML fallback), docx XML escape, sequential placeholder

- mapping, and frozen-version sync with the manuscript.

- - For AI-extension guidelines (CONSORT-AI, STARD-AI, TRIPOD+AI,

- CLAIM 2024, DECIDE-AI), also read

- `${CLAUDE_SKILL_DIR}/references/reporting_guideline_figure_map.md` —

- the row for the target guideline lists mandatory figures and which

- ones this skill cannot template (production path documented per

- row).

- - For medical-AI pipeline / DICOM / federated / architecture figures,

- also read `${CLAUDE_SKILL_DIR}/references/pipeline_concepts_medical_ai.md`.

- exemplar is bundled (`template_output*.png`, produced by this skill's own R script), Read 1–2 of

- those too; the figures cropped from published papers were removed in 2026-07 because an

- MIT-licensed package cannot redistribute them (see that directory's README). If you have your own

- exemplars locally, point the loop at them — they stay on your machine.

- For a non-flow data plot (forest, ROC, KM, calibration), read the matching anatomy model in

- source-code changes (D2 node renames, count corrections, matplotlib

- - If any item is FAIL → apply the required edits to the source (D2 file or

- Record the final state in `_figure_manifest.md` (see the manifest format

- below) so downstream steps (`/write-paper` Phase 2 embedding and Phase 7

- DOCX build) and future critic passes can see the history.

- Save final outputs:

- - **TIFF** (if the journal requires it, 300 DPI LZW compression)

- disagrees with the actual slide XML files. This script catches all four classes

- of defect codified in `~/.claude/rules/pptx-mac-compatibility.md`:

- - [ ] **Colorblind test**: Would the figure work for deuteranopia? (no red-green only distinctions)

- - [ ] **Journal specs**: Dimensions, font, and format match target journal requirements

- - [ ] **Caption**: Drafted with key finding, abbreviations, statistical details, and sample size

- When the study type is known (from `/write-paper` Phase 0 or user specification), auto-detect and generate the complete required figure set without asking for each figure individually.

- `figures/_figure_manifest.md` — one row per figure (`Figure | Path | Type | Tool | Critic |

- (DOCX build); verify it exists and is non-empty before finishing. Format and field definitions:

- `${CLAUDE_SKILL_DIR}/references/figure_manifest.md`.

-

- **Flow diagram generation rule.** STARD / CONSORT / PRISMA / STROBE flow diagrams **MUST** use the

- standardized R pipeline `scripts/generate_flow_diagram.R` (DiagrammeR + Graphviz dot + rsvg) — the

- single canonical tool for all four. Do **NOT** use matplotlib `FancyBboxPatch` (manual coordinates

- break when text changes, and patches distort when embedded in DOCX). Do **NOT** use D2 for new

- flow diagrams (weak font control, overlap needs manual post-processing). Numbers in labels must be

- CSV-derived, or hand-written only when the value lives in a commit-tracked data artifact.

-

- **Read on demand:**

-

- | File | Read it when | Cost if read blindly |

- |---|---|---|

- | `references/flow_diagram_recipe.md` | you are generating a STARD / CONSORT / PRISMA / STROBE flow diagram | ~2,200 tokens — a ROC curve or forest plot needs none of it |

- | `references/figure_manifest.md` | you are writing `_figure_manifest.md` | ~700 tokens of output format |

- Choose the right tool for each figure type. Using matplotlib for flow diagrams leads to

- hard-coded coordinates that break when text changes — use auto-layout tools instead.

-

- ### Data Visualization → matplotlib/seaborn (this skill)

-

- Best for figures where data drives the layout. This skill handles these directly:

-

- | Type | Use Case | Key Library |

- |------|----------|-------------|

- | ROC Curve | Diagnostic accuracy | matplotlib, sklearn |

- | Forest Plot | Meta-analysis | matplotlib |

- | Calibration Plot | Prediction model | matplotlib |

- | KM Curve | Survival analysis | lifelines, matplotlib |

- | Bland-Altman | Agreement | matplotlib |

- | Confusion Matrix | Classification | seaborn |

- | Box/Violin Plot | Group comparison | seaborn |

- | Bar Chart | Categorical comparison | matplotlib |

- | Heatmap | Correlation/agreement | seaborn |

- Flow diagrams require auto-layout engines. Do NOT use matplotlib patches with manual coordinates

- — this causes the "absolute coordinate hell" problem where changing one box breaks all

- downstream positions.

- **R workflow for flow diagrams:** See the "R flow diagram recipe" above in the Flow diagram generation rule. Key points: YAML config → `Rscript scripts/generate_flow_diagram.R --type <t> --config <yaml> --out <prefix>` → PDF + 300/600 dpi PNG. Templates in `references/exemplar_diagrams/{strobe,consort,prisma,stard}/template_input.yaml`.

- When a journal requires the canonical, statement-issued template (rather than

- the auto-laid-out R version), use the bundled official files in

- | STROBE (cohort) | Parametric `.pptx` builder `build_strobe_template.py` (single-script, takes YAML config) | Cohort/case-control study Figure 1 when co-authors want PowerPoint they can hand-edit. Auto-fits text, content-fits slide, dashed-border exclusion side-branches with strictly-horizontal connectors. Optional left-side phase column (omit `stages:` for the plain STROBE convention; include it for the PRISMA-style Identification/Screening/Inclusion/Analysis column). Pair with `generate_flow_diagram.R --type strobe` for the vector PDF/TIFF submission file. |

- # rows share one phase label automatically. Stage box fills auto-pick readable text color.

- The builder checks that the exclusion cascade closes — the count in a spine box, minus the

- exclusions declared after it, must equal the next spine box (`A - Σ(exclusions after A) ==

- B`), for every link that declares an exclusion. It warns loudly on any imbalance and, with

- `--strict-cascade`, refuses to build. This catches the figure-image arithmetic drift that

- text-grep and prose gates miss (a dropped exclusion leaving the figure short of the analytic

- N). Run `scripts/_strobe_cascade.py --config figure1_strobe.yaml --strict` to check a config

- without rebuilding the diagram.

- ### Visual / Graphical Abstracts → python-pptx Template Generator

-

- | Type | Recommended Tool |

- |------|-----------------|

- | Visual Abstract (any journal) | `generate_visual_abstract.py` with PPTX template |

- | Visual element illustration | Study's own figures (preferred), or free libraries (Servier/NIAID) |

- | Medical Illustration | See `${CLAUDE_SKILL_DIR}/references/medical_illustration_sources.md` |

-

- See the Visual Abstract section above for the full workflow.

-

- ### Hybrid Workflow (recommended for publication)

-

- ```

- Data plots: matplotlib/seaborn → PDF + PNG (this skill)

- Flow diagrams: generate_flow_diagram.R (DiagrammeR + rsvg) → PDF + 300/600 dpi PNG

- Final assembly: pandoc or python-docx (auto-embedded in DOCX)

- ```

-

- ## Supported Figure Types (matplotlib/seaborn)

-

- | Type | Use Case | Key Library | Output |

- |------|----------|-------------|--------|

- | ROC Curve | Diagnostic accuracy | matplotlib, sklearn | Single/multi-model ROC with AUC |

- | Forest Plot | Meta-analysis | matplotlib | Effect sizes with CIs, diamond summary |

- | Calibration Plot | Prediction model | matplotlib | Observed vs predicted with Hosmer-Lemeshow |

- | KM Curve | Survival analysis | lifelines, matplotlib | With risk table, log-rank p |

- | Bland-Altman | Agreement | matplotlib | With mean diff, +/-1.96 SD limits |

- | Confusion Matrix | Classification | seaborn | Heatmap with percentages |

- | Box/Violin Plot | Group comparison | seaborn | With individual data points |

- | Pipeline Diagram | Methods figure | D2 (preferred) or matplotlib | Processing/workflow steps |

- | Bar Chart | Categorical comparison | matplotlib | With error bars (CI or SD) |

- | Heatmap | Correlation/agreement | seaborn | Color-coded matrix |

-

- ---

-

- ## Figure Type Templates

-

- ### ROC Curve

-

- ```python

- from sklearn.metrics import roc_curve, auc

-

- fig, ax = plt.subplots(figsize=(3.5, 3.5))

- fpr, tpr, _ = roc_curve(y_true, y_score)

- roc_auc = auc(fpr, tpr)

- ax.plot(fpr, tpr, color=WONG[5], lw=1.5,

- label=f'Model (AUC = {roc_auc:.3f})')

- ax.plot([0, 1], [0, 1], 'k--', lw=0.8, alpha=0.5)

- ax.set(xlabel='1 - Specificity', ylabel='Sensitivity',

- xlim=[-0.02, 1.02], ylim=[-0.02, 1.02])

- ax.legend(loc='lower right', frameon=False)

- ```

-

- - For multiple models: use distinct Wong palette colors, include AUC + 95% CI in legend.

- - For comparison: report DeLong p-value in annotation.

-

- ### Forest Plot

-

- - Horizontal layout: effect sizes as squares (sized by weight), CIs as lines.

- - Diamond at bottom for pooled estimate.

- - Vertical dashed line at null effect (OR=1 or MD=0).

- - Axis label: "Favours A | Favours B" or appropriate.

- - Include heterogeneity stats (I-squared, p) below the diamond.

-

- ### Flow Diagrams (STROBE / CONSORT / PRISMA / STARD)

-

- **Single canonical tool: `scripts/generate_flow_diagram.R`** (see the R flow diagram recipe above). Do not fall back to matplotlib for flow diagrams — manual coordinates break when text changes and patches distort in DOCX. D2 remains a documented legacy fallback only when R is unavailable.

-

- Layout invariants:

- - Rectangular boxes with rounded corners for stages; notes (`shape: note`) for exclusion side-boxes.

- - Vertical top-down flow by default; horizontal only when the manuscript layout demands it.

- - Every box label contains the count (e.g., `"Assessed for eligibility\n(n = 450)"`).

- - Numbers are CSV-derived (numerical-safety) — author the YAML from an R/Python script that reads the upstream data, or cite the source file in a comment when a literal value is unavoidable.

- - Follow the official template layout from each guideline.

- - **Use relative positioning** — never hard-code absolute y-coordinates. Calculate each box

- position from the previous box's bottom edge plus a consistent gap constant.

- - **Define gap constants** at the top of the script (e.g., `GAP_SMALL = 1.5`, `GAP_BRANCH = 2.2`).

- - **Avoid magic number padding** in arrow endpoints — use named constants.

-

- **D2 approach (legacy fallback — use only when R is unavailable; the R script above is canonical):**

- ```bash

- d2 --layout elk --theme 0 flow.d2 output.svg

- # Then: open SVG in Figma → grid-snap → font swap → export PDF

- ```

-

- **Caption ↔ flow-SSOT reconciliation (before Step 5 Export).** The flow-diagram config (the YAML/script that `generate_flow_diagram.R` consumes) is the single source of truth for participant counts. A hand-written Figure 1 caption drifts from it whenever the cohort is re-locked but the caption is not — the classic "caption says n = 1,284 analytic, diagram box says n = 998" defect, which surfaces only at submission. Re-derive the caption counts from the flow config and reconcile:

-

- ```bash

- python3 ${CLAUDE_SKILL_DIR}/scripts/derive_figure_legend_counts.py \

- --flow-config figures/figure1_strobe_graphviz.yaml \

- --manuscript manuscript/index.qmd \

- --out qc/figure_legend_counts.json --strict

- ```

-

- Any `n = N` in the caption that is not a box count in the flow config is a `MISMATCH` (stale caption) — update the caption from the config, never the reverse. This pairs with numerical-safety's "re-derive prose counts every revision" rule and with `/sync-submission`'s cross-document N checks. (The reconciler is stdlib-only and parses the config as text, so it works regardless of the flow tool.)

-

- ### Calibration Plot

-

- - 45-degree reference line (perfect calibration).

- - Grouped observed vs predicted with error bars.

- - Report Hosmer-Lemeshow statistic and Brier score in annotation.

- - Optional: histogram of predicted probabilities at the bottom.

-

- ### Kaplan-Meier Curve

-

- - Step function with distinct colors per group.

- - Censoring marks as small vertical ticks.

- - Number-at-risk table below the plot (aligned with x-axis ticks).

- - Log-rank p-value in annotation.

- - Median survival with 95% CI if applicable.

-

- ### Bland-Altman Plot

-

- - X-axis: mean of two measurements.

- - Y-axis: difference between measurements.

- - Horizontal lines: mean difference (solid), +/-1.96 SD (dashed).

- - Annotate the mean diff and limits of agreement values.

- - Optional: proportional bias check (regression line through points).

-

- ### Confusion Matrix

-

- - Heatmap with both counts and percentages in each cell.

- - Row-normalized percentages preferred (sensitivity per class).

- - Clear axis labels: "Predicted" (x) and "Actual" (y).

- - Use sequential colormap (Blues or Greens), not diverging.

-

- ### Box/Violin Plot

-

- - Show individual data points (jittered) overlaid on box or violin.

- - Mark median and mean distinctly.

- - Statistical annotation brackets with significance stars.

- - Stars: * p<0.05, ** p<0.01, *** p<0.001, ns for non-significant.

-

- ### Pipeline Diagram

-

- - Horizontal or vertical flow of processing stages.

- - Boxes: rounded rectangles with stage name and brief description.

- - Arrows: labeled with data counts or transformation type.

- - Color-code stages by category (data collection, processing, validation).

- - Keep text minimal; use supplementary caption for details.

-

- ### Bar Chart

-

- - Error bars: 95% CI (preferred) or SD, stated in caption.

- - Individual data points overlaid if n < 30.

- - Horizontal orientation for many categories.

- - Sort by value (descending) unless order is meaningful.

-

- ### Heatmap

-

- - Annotate cells with values.

- - Use sequential colormap for correlation (coolwarm diverging if centered at zero).

- - Mask diagonal for correlation matrices.

- - Cluster rows/columns if appropriate.

-

- ---

-

- ### Colors

-

- **Wong colorblind-safe palette (default):**

- ```python

- WONG = ['#000000', '#E69F00', '#56B4E9', '#009E73',

- '#F0E442', '#0072B2', '#D55E00', '#CC79A7']

- ```

-

- **Sequential palettes (for heatmaps):**

- - Positive values: `Blues` or `Greens`

- - Diverging (centered at 0): `coolwarm` or `RdBu_r`

- - Agreement matrices: `YlOrRd`

-

- **Rules:**

- - Never use red-green only distinctions.

- - Use line style (solid, dashed, dotted) in addition to color for line plots.

- - Use marker shape in addition to color for scatter plots.

-

- ### Typography

-

- | Element | Font Size | Weight |

- |---------|-----------|--------|

- | Figure title (if any) | 10 pt | Bold |

- | Axis label | 9 pt | Regular |

- | Tick label | 8 pt | Regular |

- | Legend text | 8 pt | Regular |

- | Annotation | 8 pt | Regular |

- | Panel label (A, B, C) | 12 pt | Bold |

-

- - Font family: Arial or Helvetica (sans-serif).

- - Panel labels: uppercase bold letter, top-left of each panel.

-

- ### Layout

-

- - Minimize white space while maintaining readability.

- - Align multi-panel figures on a grid.

- - Consistent axis ranges across comparable panels.

- - No figure titles in the plot itself (title goes in the caption below).

-

- ### Statistical Annotations

- - Significance stars: * p<0.05, ** p<0.01, *** p<0.001

- - Place above comparison brackets.

- - Report exact p-value in the figure legend or caption, not in the plot.

- ---

-

- ## Journal Specifications

-

- Default dimensions (override from `figure_specs.md` if journal-specific):

-

- - **Single column**: 3.5 in (88 mm) width

- - **1.5 column**: 5.0 in (127 mm) width

- - **Double column**: 7.0 in (178 mm) width

- - **Full page**: 7.0 x 9.5 in (178 x 241 mm)

- - **DPI**: 300 minimum for halftone, 600 for line art

- - **File formats**: PDF (vector, preferred) + PNG (300 DPI)

- - **No chartjunk**: no 3D effects, no unnecessary gridlines, no decorative elements, no gradient fills

-

- ---

-

- ## Multi-Panel Figures

-

- For composite figures with multiple panels:

-

- ```python

- fig, axes = plt.subplots(nrows, ncols, figsize=(width, height))

-

- # Label each panel

- for ax, label in zip(axes.flat, 'ABCDEFGH'):

- ax.text(-0.15, 1.05, label, transform=ax.transAxes,

- fontsize=12, fontweight='bold', va='top')

- ```

-

- Common layouts:

- - 2-panel horizontal: `figsize=(7.0, 3.5)`, 1 row x 2 cols

- - 2-panel vertical: `figsize=(3.5, 7.0)`, 2 rows x 1 col

- - 2x2 grid: `figsize=(7.0, 7.0)`, 2 rows x 2 cols

- - 3-panel: `figsize=(7.0, 3.0)`, 1 row x 3 cols

-

- Use `plt.tight_layout()` or `fig.subplots_adjust()` for spacing.

-

- ---

-

- ## Caption Writing

-

- After generating each figure, draft a caption following these rules:

-

- 1. **First sentence**: Describe what the figure shows (type + key finding).

- 2. **Subsequent sentences**: Define abbreviations, explain symbols, state sample sizes.

- 3. **Statistical details**: Note the test used and significance threshold.

- 4. **Format**: "Figure {N}. {Caption text}" -- no bold, no title case.

-

- Example:

- > Figure 1. Receiver operating characteristic curves comparing the diagnostic performance of

- > the multi-agent pipeline (blue) and single-agent baseline (orange) for identifying incorrect

- > Anki flashcard content. The area under the curve was 0.92 (95% CI: 0.89-0.95) for the

- > multi-agent pipeline and 0.84 (95% CI: 0.80-0.88) for the single-agent baseline (DeLong

- > test, p = 0.003). The dashed diagonal line represents chance performance.

-

- ---

-

-

- ---

-

- ## Error Handling

-

- - If data is insufficient for the requested figure type, explain what is needed and ask the user.

- - If a figure exceeds journal dimension limits, resize and report the adjustment.

- - If text overlaps in the figure, try `tight_layout()`, reduce font size, or adjust spacing.

- - Never fabricate data points. If sample data is needed for a template demo, explicitly label it as "example data."

-

- ## CLI Tools Available

-

- ImageMagick, Ghostscript, FFmpeg are installed and can be used for post-processing:

-

- ```bash

- # Figure DPI/format conversion for journal submission

- magick input.png -density 300 -units PixelsPerInch output.tiff

- magick input.png -resize 1200x -quality 95 output.jpg

-

- # CMYK conversion (some print journals require this)

- magick input.png -colorspace CMYK output.tiff

- ```

-

- ### Portal-ready TIFF (SNAPP `.png`-not-accepted / 25 MB cap)

-

- A raw `magick ... output.tiff` keeps the alpha channel (transparent regions print **black**

- on many production pipelines) and stays uncompressed (a 600-dpi RGBA TIFF blows past a

- portal's 25 MB cap). `export_portal_tiff.py` does the flatten-and-compress a human otherwise

- does by hand and **verifies the result is pixel-identical** to that white-flatten before

- handing it over — use it when a portal accepts only `.tiff`/`.jpeg`/`.eps` (Springer Nature

- SNAPP) or caps figure size (JACC: Asia):

-

- ```bash

- python3 scripts/export_portal_tiff.py --in figure.png --out figure.tiff --max-mb 25

- # LZW-compressed, RGBA→RGB white-flattened, pixel-identity-verified; exit 1 if still over the cap

- ```

-

- ```bash

- # Multi-panel figure assembly (A/B/C/D panels)

- magick montage panelA.png panelB.png panelC.png panelD.png \

- -tile 2x2 -geometry +10+10 -density 300 combined.png

-

- # Animated figure (GIF from frame sequence)

- ffmpeg -framerate 2 -i frame_%03d.png -vf "scale=800:-1" output.gif

-

- # Video from figure sequence (for supplementary materials)

- ffmpeg -framerate 1 -i slide_%03d.png -c:v libx264 -pix_fmt yuv420p supplementary_video.mp4

- ```

-

- ## AI Image Generation (Optional)

-

- AI illustration is a **supplementary option**, not a requirement. Visual abstracts and figures

- can be completed without any API key using study figures and free illustration libraries.

-

- If `GEMINI_API_KEY` is set, the `generate_image.py` script can generate illustrations:

- ```bash

- python ${CLAUDE_SKILL_DIR}/scripts/generate_image.py \

- "Clean medical illustration of a CT-guided lung biopsy procedure, \

- flat vector style, white background, no text" \

- --output output.png --aspect 16:9

- ```

-

- Use for: procedural schematics, anatomical illustrations, pipeline diagrams.

- Always review AI output against the AI-Generated Figure Warning section above.

-

- If `GEMINI_API_KEY` is not set, guide the user to free illustration resources:

- see `${CLAUDE_SKILL_DIR}/references/medical_illustration_sources.md`.

-

- ## Language

-

- - Code and figure text: English

- - Communication with user: Match user's preferred language

- - Medical terms: English only

-

- ## Anti-Hallucination

-

- - **Never fabricate references.** All citations must be verified via `/search-lit` with confirmed DOI or PMID. Mark unverified references as `[UNVERIFIED - NEEDS MANUAL CHECK]`.

- - **Never invent clinical definitions, diagnostic criteria, or guideline recommendations.** If uncertain, flag with `[VERIFY]` and ask the user.

-

- ## Global-rule references

-

- Some passages in this skill cite a path of the form `~/.claude/rules/<name>.md`. Those are the

- maintainer's personal global rules, kept outside this repository. They are **not shipped with

- this skill** and will not exist on your machine; they appear only as provenance for where a

- convention came from. If one of them looks like it is standing in for an instruction you actually

- need, that is a bug — please open an issue, because the instruction belongs here.