medsci-skills 4.1.0

package/skills/make-figures/references/critic_rubrics/data_plot.md

@@ -0,0 +1,166 @@
+# Critic Rubric — Data Plots
+
+Apply this rubric when the generated figure is a data visualization (not a
+flow diagram): ROC, forest, KM, calibration, Bland-Altman, confusion matrix,
+box/violin, bar, heatmap. The Claude session should Read the rendered PNG
+plus any available exemplars from `references/exemplar_diagrams/{type}/`,
+then mark each item below as **PASS / PARTIAL / FAIL** with a one-line
+justification.
+
+After scoring, produce a list of concrete matplotlib/seaborn edits that
+would resolve every FAIL or PARTIAL item. Return the scored rubric + edit
+list to the user.
+
+---
+
+## A. Axes, labels, units
+
+1. **X-axis label** present with units where applicable.
+2. **Y-axis label** present with units where applicable.
+3. **Axis tick labels** readable (no overlap, sensible density, no scientific
+   notation where plain numbers fit).
+4. **Axis limits** sensible — no wasted whitespace (e.g., ROC axes should
+   be 0–1 exactly, forest plot x-axis should frame all CIs without
+   clipping).
+5. **Tick direction inward**, tick marks minor/major where needed. No
+   chart-spine clutter.
+
+## B. Legend / caption
+
+6. **Legend present** when ≥2 series are shown; placed where it does not
+   obscure data.
+7. **Legend labels** are descriptive (not "Series 1"); include N or group
+   size where relevant.
+8. **Legend ordering** matches visual order of series (top to bottom).
+9. **Caption-ready** — plot does not rely on external notes the caption
+   cannot repeat concisely.
+
+## C. Figure-type–specific requirements
+
+### ROC curve
+- AUC and 95% CI displayed on plot or in legend
+- Diagonal reference line (chance) shown
+- Sensitivity on Y-axis (0–1), 1−Specificity on X-axis (0–1)
+- Multiple models distinguished by color AND line style (grayscale-safe)
+
+### Forest plot
+- Effect estimates aligned to a vertical reference line (null effect)
+- CIs drawn as horizontal bars with appropriate caps
+- Box size proportional to study weight
+- Diamond summary at the bottom; pooled estimate and CI printed
+- Left column: study labels; right column: effect (95% CI) numeric
+- Heterogeneity statistics (I², τ², Q p-value) reported in caption or plot
+
+### KM curve
+- Number at risk table below the plot
+- Median survival and its CI shown or reported in caption
+- Log-rank p-value or Cox HR reported
+- Curves distinguishable in grayscale (line style + color)
+- Censoring marks visible
+
+### Calibration plot
+- Ideal diagonal line (y=x) shown
+- Binned observed vs. predicted points
+- Hosmer-Lemeshow p-value or Brier score reported
+- Histogram of predicted probabilities overlaid or beside the plot
+
+### Bland-Altman
+- Mean difference line
+- ±1.96 SD limits of agreement
+- LoA values printed
+- Scatter points not clipped at plot edges
+
+### Confusion matrix
+- Cells annotated with counts AND percentages
+- Axis labels "Predicted" / "Actual" (or "Reference")
+- Diagonal emphasized (darker color or heavier stroke) if useful
+
+## D. Typography and accessibility
+
+10. **Font size ≥ 8pt at final dimensions** (most journals require 6–7pt min
+    for axis numerics, 8pt for labels). At 300 DPI in a 3.5×3.5 inch
+    figure, this corresponds to roughly ≥25 px — use `critic_figure.py`
+    OCR min-height flag as a proxy.
+11. **Single font family** throughout (typically sans-serif). No mixed
+    Arial/Helvetica/Times.
+12. **Colors from Wong palette** or equivalent colorblind-safe scheme.
+    `critic_figure.py` flags out-of-palette fractions >15%.
+13. **Grayscale-safe** — every series is distinguishable in grayscale
+    conversion, either through line style, marker shape, or luminosity
+    differences.
+
+## E. Publication readiness
+
+14. **Vector PDF produced** in addition to PNG.
+15. **Dimensions match journal spec** — width per figure_specs.md for the
+    target journal (single column ≈3.5 in, double ≈7.0 in).
+16. **DPI ≥ 300 (halftone) or ≥ 600 (line art)**.
+17. **No duplicate data encoding** (e.g., color + shape + size all mapped
+    to the same variable adds clutter without information).
+18. **Statistical annotations** — where significance markers are used
+    (`*`, `**`, `***`), the caption defines thresholds. Prefer actual
+    p-values for publication.
+
+## F. Exemplar comparison (if exemplars exist for this type)
+
+19. **Visual density** comparable to exemplars — not significantly sparser
+    or more cluttered.
+20. **Annotation style** — placement of summary statistics, N labels,
+    p-values consistent with exemplars.
+
+## G. Medical AI / prediction-model checks (added v1.1.0)
+
+Apply when the figure supports a prediction-model or medical-AI claim
+(TRIPOD+AI, CLAIM 2024, STARD-AI, CONSORT-AI). Source:
+`reporting_guideline_figure_map.md` "AI-specific figures most often
+missing."
+
+21. **Calibration plot accompanies discrimination** — when the manuscript
+    reports AUC/c-statistic, a calibration plot is also presented (or the
+    figure is paired with one). TRIPOD+AI mandates calibration; AUC alone
+    is insufficient evidence of model fitness.
+22. **Subgroup / fairness panel** — when the deployment claim covers
+    multiple demographic groups, sites, or scanner vendors, performance
+    is shown stratified by at least one such axis. CLAIM 2024 §C and
+    TRIPOD+AI both require this.
+23. **Colorblind-safe + redundant encoding** — color carrying diagnostic
+    meaning is paired with at least one non-color cue (line style, marker
+    shape, or direct label) so the figure survives deuteranopia
+    simulation and grayscale conversion. (Crameri 2024.) Stronger than
+    the existing item D.13.
+24. **Dataset-flow visible** — for AI papers reporting performance on a
+    test set, the manuscript also includes a dataset-flow diagram with
+    counts at training / tuning / internal-test / external-test splits.
+    Required by STARD-AI, CLAIM 2024, TRIPOD+AI. If the figure under
+    review is not the dataset-flow itself, confirm one exists elsewhere
+    in the manuscript.
+25. **Decision-curve analysis (when claiming clinical utility)** — papers
+    that argue "this model would change clinical management" must
+    accompany discrimination/calibration with a decision-curve plot
+    (Vickers & Elkin, *Med Decis Making* 2006). Recommended by TRIPOD+AI.
+
+---
+
+## Scoring output format
+
+```
+## Critic report (data plot, round T)
+
+| Item | Score | Note |
+|------|-------|------|
+| A.1 X-axis label | PASS | — |
+| A.2 Y-axis label | FAIL | Missing units ("Sensitivity" should be unitless OK; but "Time" needs "(months)") |
+| ...
+
+### Required edits before next render
+1. Add unit "(months)" to Y-axis label.
+2. Increase legend font from 6pt to 8pt.
+3. ...
+
+### Overall verdict
+[ ] PASS — ready for manuscript
+[ ] REFINE — items above must be fixed before next round
+```
+
+Record `critic_pass: yes | partial | no` and `refine_rounds: N` in the
+`_figure_manifest.md` for this figure after the final round.

package/skills/make-figures/references/critic_rubrics/flow_diagram.md

@@ -0,0 +1,169 @@
+# Critic Rubric — Flow Diagrams
+
+Apply this rubric when the generated figure is a flow diagram: STARD,
+CONSORT, PRISMA, or pipeline/methods. The Claude session should Read the
+rendered PNG plus any available exemplars from
+`references/exemplar_diagrams/{stard|consort|prisma|pipeline}/`, then mark
+each item below as **PASS / PARTIAL / FAIL** with a one-line justification.
+
+After scoring, produce a concrete list of source edits (D2 code changes,
+node label fixes, count corrections) that would resolve every FAIL or
+PARTIAL item. Return the scored rubric + edit list to the user.
+
+---
+
+## A. Structural integrity
+
+1. **Box overlap** — No two boxes or text labels overlap. Arrows do not cross
+   through node text.
+2. **Readable edges** — Every edge has a clear source and target; direction is
+   unambiguous; no dangling arrows.
+3. **Hierarchy preserved** — Vertical or horizontal flow reads in a single
+   dominant direction; upstream nodes appear before downstream ones.
+4. **Alignment** — Peer nodes at the same logical level are aligned
+   (baseline or center).
+5. **Whitespace** — No excessive vertical gap (>2× box height) between
+   sequential steps. No cramped collisions at decision points.
+
+## B. Required elements (per figure type)
+
+### STARD flow (diagnostic accuracy)
+- Enrollment count (consecutive vs. random, eligible n)
+- Included n (with inclusion criteria applied)
+- Excluded n with itemized reasons
+- Index test performed (n analyzed)
+- Reference standard performed (n analyzed)
+- Final analysis cohort (n with both tests)
+
+### CONSORT flow (RCT)
+- **Enrollment** section: Assessed for eligibility (n), Excluded (n with
+  reasons: did not meet criteria, declined, other)
+- **Allocation** section: Randomized (n), Allocated to each arm (n received /
+  n did not receive intervention)
+- **Follow-up** section: Lost to follow-up (n, reasons), Discontinued (n,
+  reasons) per arm
+- **Analysis** section: Analyzed (n), Excluded from analysis (n, reasons)
+  per arm
+
+### PRISMA 2020 flow (systematic review)
+- Records identified from databases (n per database)
+- Records identified from other sources (registers, citation search, etc.)
+- Records after duplicates removed (n)
+- Records screened (n) → Records excluded (n)
+- Reports sought for retrieval (n) → Reports not retrieved (n)
+- Reports assessed for eligibility (n) → Reports excluded with reasons (n, reason categories)
+- Studies included in review (n) / Reports of included studies (n)
+
+### Pipeline / methods
+- Input data block clearly named (modality, cohort)
+- Preprocessing steps in sequence (resampling, normalization, augmentation)
+- Model / algorithm block with name or architecture
+- Output / task block (segmentation, classification, regression)
+- Evaluation metric block where applicable
+
+## C. Numerical consistency
+
+6. **Arithmetic balance** — At each branching node, `in = out + excluded`.
+   Verify every subtraction explicitly. Flag any mismatch.
+7. **Column totals consistent** — For parallel arms (CONSORT), arm totals
+   sum to the randomized total at every stage.
+8. **No duplicate counts** — A participant should not appear in two leaf
+   nodes unless the diagram explicitly models this.
+9. **Manuscript consistency** — Numbers in the diagram match the
+   corresponding text in Methods/Results (apply the [VERIFY-CSV] rule —
+   every count should trace to a CSV cell or source query).
+
+## D. Typography and accessibility
+
+10. **Font size ≥ 18pt** at the compact-recipe render dimensions (main boxes
+    ≥ 20pt, exclusion boxes ≥ 18pt, italic notes ≥ 17pt). Check against the
+    `critic_figure.py` OCR min-height flag.
+11. **No truncated text** — No box shows clipped text ("Assessed for eli...").
+    OCR coverage check (source_word_coverage ≥ 0.95).
+12. **Consistent casing** — Sentence case everywhere, or Title Case
+    everywhere — not mixed.
+13. **Wong palette or neutral only** — Fill colors drawn from the Wong
+    colorblind-safe set plus whites/light grays. No red-green only
+    distinctions.
+14. **Grayscale-safe** — Conversion to grayscale preserves all distinctions
+    between box categories (intent vs. exclusion vs. outcome).
+
+## E. Publication readiness
+
+15. **Vector format available** — Both PNG (for DOCX embedding) and PDF
+    (for journal submission) were produced. If PDF missing, flag.
+16. **Dimensions match journal spec** — Width matches the target journal's
+    single-column or double-column specification (±0.3 in).
+17. **DPI meets spec** — ≥600 DPI for line-art submissions, ≥300 DPI for
+    halftone.
+18. **Policy compliance** — Tool is D2 or a permitted auto-layout engine,
+    not matplotlib FancyBboxPatch and not Mermaid. (Mermaid is forbidden
+    in papers per the project's figure-toolchain policy.)
+
+## F. Exemplar comparison (if exemplars exist for this type)
+
+19. **Hierarchy depth** matches one of the exemplars within ±1 level.
+20. **Typographic weight** — Main step labels are visually heavier
+    (bold/larger) than parenthetical / exclusion labels, as in the
+    exemplars.
+21. **Emphasis placement** — Key cohort counts (final analysis n, primary
+    outcome n) are visually emphasized (thicker stroke, larger font, or
+    fill distinction), consistent with exemplar conventions.
+
+## G. Communication-first checks (added v1.1.0)
+
+These checks operationalize `references/design_principles.md` (Nature Hum
+Behav 2026) and `references/flow_diagram_lessons.md`. Apply when the
+diagram will be circulated to senior co-authors or submitted to a peer-
+reviewed venue.
+
+22. **Cognitive load** — Each column has ≤7 boxes; each diagram uses ≤3
+    distinct shapes (e.g., rectangle / rounded rectangle / note) and ≤3
+    fill colors. If the count is exceeded, fold detail into supplementary
+    or split into a multi-panel figure.
+23. **Key-message visibility** — The analytic cohort (final n included in
+    primary analysis) is visually emphasized via thicker stroke
+    (`penwidth ≥ 1.8`), distinct fill, or larger font, so the reader's
+    eye lands on it within 2 seconds.
+24. **Official-template fidelity** (when applicable) — Layout matches the
+    canonical PRISMA 2020 / CONSORT 2010 / STARD 2015 / STROBE template
+    used by the corresponding statement group. Custom layouts are
+    acceptable for exploratory drafts but must be replaced before
+    circulation. (See `flow_diagram_lessons.md` Lesson 1.)
+25. **Exclusion-box geometry** — Exclusion side-boxes are rectangles (not
+    `shape: note` / "dog-ear" style) when the diagram aims to match
+    PRISMA / CONSORT canonical look. Bullets within exclusion boxes are
+    left-aligned (Graphviz `\l`, not `\n`).
+26. **Frozen-version sync** — The figure file path includes the manuscript
+    version (`figures/v{N}/figure_1.pdf`) and the value of `v{N}` matches
+    the current manuscript version. Edits after circulation must branch
+    to `v{N+1}/`, never overwrite `v{N}/`. (See `flow_diagram_lessons.md`
+    Lesson 5.)
+
+---
+
+## Scoring output format
+
+```
+## Critic report (flow diagram, round T)
+
+| Item | Score | Note |
+|------|-------|------|
+| A.1 Box overlap | PASS | — |
+| A.2 Readable edges | PASS | — |
+| ...
+| C.6 Arithmetic balance | FAIL | Enrollment 500 ≠ Included 420 + Excluded 85 (off by 5) |
+| ...
+
+### Required edits before next render
+1. Correct Excluded count in node X from 85 to 80.
+2. Increase font-size of "Analysis" subsection header from 18 to 22.
+3. ...
+
+### Overall verdict
+[ ] PASS — ready for manuscript
+[ ] REFINE — items above must be fixed before next round
+```
+
+Record `critic_pass: yes | partial | no` and `refine_rounds: N` in the
+`_figure_manifest.md` for this figure after the final round.

package/skills/make-figures/references/design_principles.md

@@ -0,0 +1,181 @@
+# Effective Scientific Figure Design
+
+> **Primary source**: Brunner et al., "Designing effective figures for
+> scientific communication." *Nat Hum Behav* (2026).
+> DOI: 10.1038/s41562-026-02466-9 — communication-context strategies.
+>
+> **Companion sources** (cite in figure legends / Methods when used):
+> - Rougier et al., "Ten simple rules for better figures." *PLoS Comput
+>   Biol* 2014;10:e1003833 (PMID 25210732). General-purpose, foundational
+>   ten-item checklist.
+> - Crameri F., "Choosing the right colors: a perceptually uniform,
+>   colorblind-safe approach." *Curr Protoc* 2024;4:e1126
+>   (DOI 10.1002/cpz1.1126). Definitive 2024 reference for `viridis`,
+>   `cividis`, `batlow` palettes and redundant encoding.
+>
+> **Triggered from**: SKILL.md Step 1 ("Specify"). Read this file **before**
+> choosing a figure type — it shifts focus from "which chart fits the data" to
+> "what message should the reader walk away with."
+
+Most figure-design guidance focuses on technical execution (axis ranges,
+palettes, DPI). This file complements that by adding a communication-first
+layer: who reads the figure, under what time pressure, and what should they
+remember 10 seconds later. Apply these strategies in Step 1 when specifying a
+figure; revisit during Step 4 / 4b when reviewing.
+
+---
+
+## The 5 strategies (read in order)
+
+### 1. Identify the key message *(most important)*
+
+Before opening a plotting library, write **one sentence** describing what the
+figure must convey. If you cannot, the figure is premature. Examples:
+
+- "Model A outperforms Model B at every operating threshold."
+- "Adverse-event rates differ by route of administration but not by dose."
+- "The proposed pipeline runs end-to-end in under 30 seconds per case."
+
+Pin that sentence as a comment at the top of the generation script. Every
+panel, color, annotation, and label exists to support that message; anything
+that does not should be removed or moved to supplementary material.
+
+### 2. Consider time and interaction (audience-aware)
+
+Different reading contexts allow different amounts of inspection time:
+
+| Context | Reading time | Implication |
+|---|---|---|
+| Journal article (specialist) | 30–120 s per figure | Dense detail acceptable; legend lookups OK |
+| Conference slide | 15–30 s, narrated | Direct labels mandatory; one message per slide |
+| Visual / graphical abstract | 5–10 s, no narration | One panel; minimal text; readable thumbnail |
+| Social-media share | 2–5 s | Self-contained; large fonts; high contrast |
+| Public lecture / press | 10–30 s, narrated | Plain-language axis labels; analogy via icon |
+
+Set the **reading-time budget** in Step 1, then design backwards. If the same
+result will appear in a journal article *and* a conference talk, build two
+distinct versions — the conference version usually drops half of what the
+journal version contains.
+
+### 3. Choose the right graph type and use color intentionally
+
+The graph type should match the structure of the data, not aesthetic
+preference.
+
+| Data structure | Default | Avoid |
+|---|---|---|
+| One continuous variable, one group | Histogram, density | Pie chart |
+| Two continuous variables | Scatter (+ regression line if appropriate) | Bar chart |
+| Continuous over time | Line | Stacked bar |
+| Categorical proportions | Bar (sorted), waffle | 3-D pie |
+| Distribution by group | Box / violin / strip | Bar with SD error |
+| Diagnostic performance | ROC, PR curve | Single accuracy bar |
+| Effect size with CI | Forest plot, dot-and-whisker | Bar with asterisks |
+| Workflow / cohort | Flow diagram (PRISMA / CONSORT / STARD) | Free-form arrows |
+
+Color rules (compatible with this skill's `figure_specs.md`; full
+justification in Crameri 2024):
+
+- **Categorical groups**: Wong palette (8 colorblind-safe colors).
+- **Sequential magnitude**: `viridis` or `cividis` (perceptually uniform,
+  colorblind-safe). Avoid `jet` and `rainbow` — they introduce false
+  perceptual edges.
+- **Diverging around zero**: `RdBu`, `PuOr`, or `vik` (Crameri).
+- **Encode meaning, not decoration.** If the same conclusion holds in
+  grayscale, color is decorative — remove or use neutral grays.
+- **Redundant encoding** when color carries diagnostic information: pair
+  color with line style, marker shape, or direct label so the figure
+  survives a deuteranopia simulation and a black-and-white print.
+- **Maximum 3 colors per panel** unless the data structure genuinely demands
+  more (and then label each directly, not via legend).
+
+### 4. Reduce cognitive load
+
+Every visual element competes for attention. The reader's working memory is
+roughly 7 items; design under that ceiling.
+
+- ≤7 distinct visual elements per panel (curves, boxes, annotations).
+- ≤3 distinct shapes (e.g., square, circle, triangle).
+- ≤3 colors as above.
+- **Direct labels on series > legend.** Legend lookups cost ~2 seconds each.
+- No 3-D, drop-shadow, gradient fill, or rotated axis labels unless they
+  encode data.
+- Sans-serif font ≥ 9 pt at print size; ≥ 18 pt for slides; ≥ 24 pt for
+  posters.
+- Whitespace is not wasted space — it groups related elements.
+
+If a panel violates two or more of these, split it into multiple panels or
+move detail to supplementary material.
+
+### 5. Ask whether a figure is really needed
+
+Sometimes a table, a single sentence, or a caption-only number conveys the
+result more clearly. Use a figure when **at least one** of the following is
+true:
+
+- The reader needs to perceive a *shape* (trend, distribution, threshold).
+- The reader needs to *compare* across many groups simultaneously.
+- The result depends on a *spatial* or *anatomical* relationship.
+- The audience will not read the prose carefully and needs a visual hook.
+
+Otherwise, prefer a small table or in-line text. A 3-row × 2-column results
+table beats a bar chart of two values.
+
+---
+
+## Decision: figure vs table
+
+| Use a **figure** when… | Use a **table** when… |
+|---|---|
+| Trend or shape matters | Exact values matter (e.g., baseline characteristics) |
+| ≥4 groups / conditions | ≤3 groups *and* ≤8 metrics |
+| Distribution shape conveys meaning | Categorical labels with counts |
+| Comparison across many dimensions | Reader will reuse the numbers (re-analysis, replication) |
+| Visual-abstract / hero panel | Supplementary detail |
+
+When in doubt, sketch both on paper for 60 seconds and decide which the eye
+finishes first.
+
+---
+
+## Cognitive load checklist (Step 4 quick scan)
+
+- [ ] One sentence describes the key message in the script comment.
+- [ ] Reading-time budget matches the deployment context.
+- [ ] ≤7 visual elements per panel.
+- [ ] ≤3 colors carrying meaning (not decoration).
+- [ ] No 3-D / shadow / gradient unless data-driven.
+- [ ] Direct labels on series; legend has ≤4 entries.
+- [ ] Font size meets context minimum (9 pt print / 18 pt slide / 24 pt poster).
+- [ ] Same figure works in grayscale (run a `convert -colorspace Gray` test).
+
+If two or more boxes are unchecked, return to Step 1 before exporting.
+
+---
+
+## Anti-patterns (drawn from this skill's critic rubrics)
+
+These compose with the more granular checks in
+`critic_rubrics/data_plot.md` and `critic_rubrics/flow_diagram.md`:
+
+- **Default-palette syndrome** — using the matplotlib `tab10` palette without
+  thought. Reads as a quick draft, not a finished figure.
+- **Legend-dependence** — colored series without direct labels, forcing
+  back-and-forth between legend and data.
+- **Decorative 3-D** — bars or pies in 3-D with no third data dimension.
+- **Chart-of-three-values** — figure where a sentence would be clearer.
+- **Caption-as-Methods** — caption explains how the data were generated
+  rather than what to look at; methodology belongs in the Methods section.
+- **Mismatched detail** — slide-deck figure rendered at 6 pt because it was
+  copied from the manuscript without adjustment.
+
+---
+
+## Cross-references
+
+- `critic_rubrics/data_plot.md` — quantitative critic checks for non-flow figures
+- `critic_rubrics/flow_diagram.md` — extended checks for flow diagrams
+- `figure_specs.md` — journal-specific dimensions and DPI
+- `flow_diagram_lessons.md` — production lessons specific to PRISMA / CONSORT / STARD
+- `reporting_guideline_figure_map.md` — which figures CONSORT-AI / TRIPOD+AI / CLAIM 2024 / STARD-AI mandate
+- `pipeline_concepts_medical_ai.md` — DICOM workflow, annotation, federated learning, model architecture conventions

package/skills/make-figures/references/exemplar_diagrams/README.md

@@ -0,0 +1,65 @@
+# Exemplar Diagrams — Quality Anchors for the Critic Loop
+
+This directory holds a small, hand-curated set of flow-diagram and figure
+examples from published papers that we consider high-quality. The Critic
+Loop references these as "visual structure first" anchors when reviewing
+newly generated figures.
+
+## Layout
+
+```
+exemplar_diagrams/
+├── strobe/      # cohort / cross-sectional / case-control flow
+├── stard/       # diagnostic-accuracy flow diagrams
+├── consort/     # RCT participant flow
+├── prisma/      # systematic review selection flow
+├── pipeline/    # methods / algorithm flow diagrams
+└── {other...}/  # future types (roc, forest, km, ...)
+```
+
+Each category directory can hold two kinds of files:
+
+1. **Review anchors** (for the Critic Loop) — groups of three files per exemplar:
+   - `{label}.png` — rendered figure cropped from a published paper (≥300 DPI)
+   - `{label}.meta.yaml` — attribution metadata (source PDF, page, DOI, crop coords)
+   - `{label}_why.md` — 50–100 word note on why this figure is a good anchor
+2. **Generation templates** (for `generate_flow_diagram.R`) — one set per category:
+   - `template_input.yaml` — minimal schema example showing all supported fields
+   - `template_output.{pdf,png,_600.png}` — rendered reference output for the template
+   - Render with `Rscript ../../scripts/generate_flow_diagram.R --type <type> --config <dir>/template_input.yaml --out <dir>/template_output`
+
+## How to add a new exemplar
+
+```bash
+python skills/make-figures/scripts/extract_exemplar_from_pdf.py \
+    --pdf "/path/to/paper.pdf" \
+    --page 3 \
+    --type stard \
+    --label LastnameYEAR_STARD \
+    --doi 10.1148/radiol.2017170371 \
+    --crop 0.05,0.1,0.95,0.6
+```
+
+Then open the generated `{label}_why.md` and fill in the curator's note
+(50–100 words on hierarchy, whitespace, typography, emphasis, color).
+
+## Curator guidelines
+
+- **Source quality** — prefer examples from Radiology, NEJM, Lancet, JAMA,
+  European Radiology, BMJ, Cochrane Reviews. Lower-tier sources only when
+  they show a specifically good design pattern.
+- **One exemplar per design principle** — do not add five near-identical
+  examples. Aim for 3–5 exemplars per category, each illustrating a
+  different design strength.
+- **Crop tightly** — remove surrounding caption and whitespace so the
+  exemplar is purely the diagram.
+- **No open-access conflict** — avoid exemplars from paywalled figures
+  where fair-use for internal reference review is unclear. Prefer
+  open-access or CC-licensed papers when possible.
+
+## Attribution
+
+Exemplars are used under fair-use for internal quality review only. They
+are **not redistributed as part of generated figures** — the Critic Loop
+uses them read-only as anchors for feedback. The `_meta.yaml` sidecar
+records DOI and source for every exemplar.

package/skills/make-figures/references/exemplar_diagrams/consort/README.md

@@ -0,0 +1,15 @@
+# consort Exemplars
+
+This directory will hold 3–5 hand-curated consort flow/figure exemplars.
+Use the extraction script to add one:
+
+```bash
+python skills/make-figures/scripts/extract_exemplar_from_pdf.py \
+    --pdf "/path/to/paper.pdf" \
+    --page N \
+    --type consort \
+    --label LastnameYEAR_CONSORT \
+    --doi 10.xxxx/yyyy
+```
+
+See `../README.md` for curation guidelines.

package/skills/make-figures/references/exemplar_diagrams/consort/template_input.yaml

@@ -0,0 +1,37 @@
+# CONSORT parallel-arm RCT flow diagram template.
+# Render with:
+#   Rscript ../../scripts/generate_flow_diagram.R \
+#       --type consort --config template_input.yaml --out template_output
+rankdir: TB
+nodes:
+  - id: assessed
+    label: "Assessed for eligibility\n(n = 500)"
+  - id: excl
+    shape: note
+    fontsize: 10
+    label: "Excluded (n = 100):\n• Not meeting inclusion criteria: 60\n• Declined to participate: 25\n• Other reasons: 15"
+    rank_same_with: assessed
+  - id: rand
+    label: "Randomized\n(n = 400)"
+    highlight: true
+  - id: alloc_tx
+    label: "Allocated to intervention (n = 200)\n• Received intervention (n = 195)\n• Did not receive intervention (n = 5)"
+  - id: alloc_ctrl
+    label: "Allocated to control (n = 200)\n• Received control (n = 198)\n• Did not receive control (n = 2)"
+  - id: fu_tx
+    label: "Lost to follow-up (n = 8)\nDiscontinued intervention (n = 4)"
+  - id: fu_ctrl
+    label: "Lost to follow-up (n = 6)\nDiscontinued control (n = 3)"
+  - id: ana_tx
+    label: "Analyzed (n = 200)\n• Excluded from analysis (n = 0)"
+  - id: ana_ctrl
+    label: "Analyzed (n = 200)\n• Excluded from analysis (n = 0)"
+edges:
+  - {from: assessed, to: rand}
+  - {from: rand, to: alloc_tx}
+  - {from: rand, to: alloc_ctrl}
+  - {from: alloc_tx, to: fu_tx}
+  - {from: alloc_ctrl, to: fu_ctrl}
+  - {from: fu_tx, to: ana_tx}
+  - {from: fu_ctrl, to: ana_ctrl}
+  - {from: assessed, to: excl, style: dashed, arrow: false, constraint: false}

package/skills/make-figures/references/exemplar_diagrams/other/other_02.meta.yaml

@@ -0,0 +1,4 @@
+# Exemplar metadata (YAML)
+label: "other_02"
+figure_type: "other"
+dpi: 300

package/skills/make-figures/references/exemplar_diagrams/other/other_02_why.md

@@ -0,0 +1,13 @@
+# Why this exemplar is good — other_02 (bubble chart landscape)
+
+Hierarchy / structure: A landscape scatter/bubble chart with time on the X-axis (pre-2022 → 2025) and MMLU score on the Y-axis. A dashed logistic-like trajectory connects the frontier models across years, implicitly communicating the field-wide progression without a separate annotation layer.
+
+Whitespace & balance: The pre-2022 region is nearly empty by design — the sparseness is informative, not wasted. High-performance cluster in 2024–2025 is where bubbles densely overlap, and the axis range (0–100 MMLU) leaves enough headroom above the top models to signal the 90%+ ceiling.
+
+Typography (font size, weight, alignment): Model names are placed adjacent to their bubbles with consistent font size; no leader lines are needed because the labels sit directly on or beside each dot. The reference lines ("85% = human expert", "70% = ideal") are low-contrast gray so they guide without competing.
+
+Emphasis (which elements are visually strongest, why): Bubble size encodes release prominence, and color encodes the parent organization — two independent visual channels that give the reader a comparative read without returning to the legend.
+
+Color usage: Eight distinct organizational colors placed against a white field. The palette is high-saturation but the bubbles are translucent, which lets overlapping dots remain legible.
+
+Weaknesses (if any — nothing is perfect): The legend (top) is cramped and would benefit from more horizontal space. A few labels ("DeepSeek", "Claude 3.5 Sonnet") clip against neighbors in the 2024 cluster. No explicit units or source note in the rendered crop.