Visualization Check

Iterative review cycle using a context-free subagent as a naive reader. The subagent sees ONLY the image — no study context, no axis explanations, no expected conclusions. If the subagent can't understand the figure, a real reader won't either.

When to Use

• After generating a figure (R, Python, or any tool)

• Before submitting figures for publication

• When a plot feels unclear but you can't pinpoint why

• When you want objective "fresh eyes" feedback

Workflow

digraph viz_check { rankdir=TB; node [shape=box];

start [label="User provides image path\n(and optionally the generating script)" shape=doublecircle]; preprocess [label="Downscale to preview\n(sips → /tmp)"]; launch [label="Dispatch review subagent\n(read-only, context-free)"]; feedback [label="Subagent returns structured report:\ncomprehension / issues / rating"]; decide [label="Clarity >= 4 AND\nmain message correct?" shape=diamond]; analyze [label="Map feedback to\nactionable script changes"]; fix [label="Edit generating script\n+ apply viz best practices"]; render [label="Re-render the figure"]; done [label="Figure passes naive reader test\n— DONE" shape=doublecircle];

start -> preprocess; preprocess -> launch; launch -> feedback; feedback -> decide; decide -> done [label="yes"]; decide -> analyze [label="no"]; analyze -> fix; fix -> render; render -> preprocess [label="downscale new\nrender + dispatch\nfresh subagent"]; }

Step 0: Preprocess Image for Subagent

High-DPI publication figures (300 DPI, 2000-4500px wide) consume excessive context tokens and can cause subagents to hit context limits. Always downscale before dispatching.

Preprocessing Command

Use sips (built into macOS) to create a preview copy:

sips --resampleWidth 800 "{ORIGINAL_PATH}" --out "/tmp/viz_check_preview.png"

Rules

• Always downscale before dispatching, regardless of file size. This is cheap and prevents failures.

• Preview goes to /tmp/ — never modify the original figure.

• Use the preview path (/tmp/viz_check_preview.png ) in the subagent prompt, not the original.

• Re-preprocess after each re-render — the original changes, so the preview must be regenerated.

• For multi-figure parallel mode, use unique filenames: /tmp/viz_check_preview_{basename}.png

Multi-Figure Preprocessing

When reviewing multiple figures in parallel, batch-preprocess first:

for fig in path/to/figures/*.png; do basename=$(basename "$fig") sips --resampleWidth 800 "$fig" --out "/tmp/viz_check_preview_${basename}" done

Then dispatch each subagent with its corresponding /tmp/viz_check_preview_{basename}.png .

Step 1: Dispatch Naive Reader Subagent

You MUST dispatch a review subagent for each review round. Do not attempt to self-review — the whole point is context-free eyes.

Subagent Configuration

Setting Value Why

subagent_type

Explore

Read-only tools only (Read, Glob, Grep). Prevents accidental modifications to scripts or figures.

max_turns

3

Subagent only needs to read the image and write the report.

Resume NEVER Each round uses a fresh subagent. Never resume a previous reviewer.

Subagent Prompt Template

You are a naive reader seeing this figure for the first time. You have NO context about the study, data, or purpose. Read the image file, then produce a structured review.

Image

Read the image at: {PREVIEW_PATH}

Structured Review Template

A. Comprehension (what you understood)

1. What is this figure showing? Describe in your own words.
2. What are the axes/labels? Summarize each.
3. What is the main message or takeaway?

B. Confusion Points (what is unclear)

List EVERY element that is unclear, ambiguous, or hard to read. Be specific — reference position (top-left, bottom panel, etc.) and quote any problematic text.

C. Visual Quality Checklist

For each item, mark PASS / FAIL / N/A:

• Colors distinguishable (also in grayscale?)
• All text readable at this size (no overlapping labels?)
• Reference lines / thresholds labeled
• No unnecessary chart junk (gridlines, borders, decorations)
• Legend (if any) self-explanatory without context
• Good data-ink ratio (data vs non-data elements)
• Abbreviations spelled out or self-evident

D. Clarity Rating

Rate 1 (incomprehensible) to 5 (instantly clear). Justify in one sentence.

E. Top 3 Recommended Fixes

Prioritized list of the most impactful improvements.

Context Contamination Rules

Do NOT include in the subagent prompt:

• Study description or purpose

• What the axes represent

• Expected conclusions or trends

• Variable names or domain terminology explanations

• Prior feedback from previous iterations

• The generating script or its path

Even saying "this is a survival curve" gives away too much. Let the subagent figure it out.

Step 2: Analyze Feedback

Map the subagent's confusion points to specific script changes:

Subagent Says Likely Fix

"Can't read axis labels" Increase axis.text size, reduce tick density

"Don't know what colors mean" Add/improve legend, use more distinct palette

"Too many lines/elements" Simplify: fewer series, facet instead of overlay

"What's this dotted line?" Label reference lines directly on plot

"Can't tell the trend" Increase line width, reduce noise, add smoothing

"Axes are confusing" Better axis titles, consider log scale, add units

"Too cluttered" Remove gridlines, reduce chart junk, increase whitespace

"Colors look similar" Use colorblind-safe palette (viridis, okabe-ito)

"Abbreviation unclear" Spell out on first use, or add subtitle/footnote

Step 3: Apply Data Visualization Best Practices

Hierarchy of Fixes (Most Impact First)

• Labels and titles: Self-explanatory axis labels WITH units. No abbreviations.

• Reference lines: Label directly on plot (not just in legend).

• Color: Colorblind-safe, distinguishable in grayscale. Use scale_color_viridis_d() or Okabe-Ito.

• Simplify: Remove redundant gridlines, borders, backgrounds. theme_minimal() or theme_classic() .

• Text size: All text readable at final print size (typically 8-10pt minimum).

• Data-ink ratio: Maximize data, minimize decoration.

• Direct labeling: Label lines/points directly instead of using legends when possible.

R-Specific Patterns

Good defaults for publication figures

theme_publication <- theme_minimal(base_size = 14) + theme( axis.title = element_text(size = 14, face = "bold"), axis.text = element_text(size = 12), legend.position = "bottom", panel.grid.minor = element_blank(), plot.title = element_text(size = 16, face = "bold") )

Colorblind-safe palettes

scale_color_viridis_d() # Sequential scale_color_brewer(palette = "Set2") # Categorical

Step 4: Re-render and Iterate

• Edit the generating script with fixes (fix the SOURCE, not the PNG)

• Re-run the script to produce updated figure

• Re-preprocess: sips --resampleWidth 800 the new render to /tmp/ (the old preview is stale)

• Dispatch a NEW subagent (fresh context, same template) pointing at the new preview

• Exit condition: Subagent rates clarity >= 4/5 AND identifies the main message correctly

Typical iterations: 2-3 rounds.

Multi-Figure Mode

When checking multiple independent figures, dispatch review subagents in parallel — one per figure. Each subagent touches only its own image (no shared state).

digraph multi_fig { rankdir=LR; node [shape=box]; dispatch [label="Dispatch N subagents\nin parallel"]; fig1 [label="Subagent 1\nreviews fig1.png"]; fig2 [label="Subagent 2\nreviews fig2.png"]; fig3 [label="Subagent 3\nreviews fig3.png"]; collect [label="Collect all reports\nand fix sequentially"];

dispatch -> fig1; dispatch -> fig2; dispatch -> fig3; fig1 -> collect; fig2 -> collect; fig3 -> collect; }

For figures that share visual consistency requirements (same color scheme, axis style), do a final synthesis step after individual reviews to check cross-figure consistency.

Common Pitfalls

• Leaking context to subagent: The #1 failure mode. Review your prompt before dispatching.

• Reusing the same subagent: Prior feedback contaminates. Always dispatch fresh.

• Over-iterating: If the subagent gets the main message right but nitpicks aesthetics, you're done.

• Ignoring the generating script: Fix the SOURCE (R/Python script), not the PNG. Ensures reproducibility.

• Using general-purpose subagent: Use Explore (read-only) to prevent the reviewer from accidentally modifying files.

Quick Start

/visualization-check path/to/figure.png

If you also know the generating script:

/visualization-check path/to/figure.png --script path/to/plot_script.R

The agent will:

• Find the generating script (if not provided, search for it)

• Downscale to /tmp/ preview (sips --resampleWidth 800)

• Dispatch naive reader subagent with preview path (read-only, context-free)

• Collect structured feedback report

• Edit the script and re-render

• Re-preprocess + dispatch new subagent for re-review

• Repeat until clarity >= 4/5