good-figure

name	good-figure
description	Define and create publication-quality research figures from raw experimental data. Use when plotting experimental results, choosing figure types, refining paper figures, or reviewing whether a figure communicates the intended scientific claim.
triggers	["good figure","research figure","publication-quality figure","plot experimental results","raw experimental data","paper figures","figure design","visualization"]

Good Figure

Use this skill when an agent needs to define, create, refine, or review a research figure for a paper, report, poster, slide, or appendix.

The goal is not merely to make a plot prettier. The goal is to make a figure that communicates a scientific claim faithfully, quickly, and reproducibly from raw experimental data.

Definition

A good research figure is a compact visual argument. A reader should be able to understand the intended claim, the comparison being made, the evidence supporting it, and the main caveats within a few seconds of first seeing the figure.

A good figure has all of these properties:

1. Claim-first: the figure exists to support one primary claim, not to display every available number.
2. Faithful to raw data: all filtering, aggregation, normalization, and uncertainty are explicit and reproducible.
3. Right comparison unit: the visual grouping matches the research question. Do not average across models, benchmarks, seeds, or tasks unless the averaged quantity has a clear scientific meaning that can be stated in one sentence.
4. Self-contained: axis labels, legends, annotations, and captions let the reader understand what each mark means without reading the full method section first.
5. Attention-managed: color, size, line weight, annotation, and layout direct attention to the intended conclusion, not to incidental styling.
6. Manuscript-ready: font sizes, line widths, panel sizes, colors, and captions remain readable after the figure is inserted into the final paper layout.
7. Review-resistant: the figure avoids unnecessary details that invite distracting questions, such as unexplained extra lines, unsupported correlation statistics, or ambiguous metric names.

Required output from the agent

Before writing plotting code, produce a figure specification:

Figure claim:
Raw data source:
Experimental unit:
Rows excluded or filtered:
Primary grouping variables:
Aggregation and uncertainty:
X axis:
Y axis:
Color / marker / line encodings:
Panel layout:
Annotation plan:
Caption draft:
Known caveats:
Export format and target size:

If any field is unknown, ask the user or inspect the data before plotting.

Raw-data-to-figure workflow

1. State the claim

Write the figure claim as one sentence.

Good examples:

• "Most models are over-optimistic about whether they can finish a task under the budget."
• "Better models recognize failed trajectories earlier, enabling earlier stop-loss decisions."
• "Token usage increases near the end of failed rollouts, but the magnitude differs by model."

Bad examples:

• "Show all results."
• "Plot accuracy over time."
• "Make the current figure nicer."

If the claim cannot be stated, the figure is not ready to draw. First decide whether the figure belongs in the main paper, appendix, or an internal debugging notebook.

2. Audit the raw data

Inspect the raw table before aggregating.

Check:

• What is one row: run, task, rollout, turn, seed, model, benchmark, or metric?
• Which columns are identifiers, treatments, measurements, metadata, and derived metrics?
• Units: tokens, turns, dollars, seconds, percent, normalized reward, or binary success.
• Missing values and failed runs.
• Number of samples per group.
• Whether repeated measures create dependence between rows.
• Whether task difficulty or benchmark distribution differs across groups.
• Whether any threshold was chosen after seeing results.

Keep raw data immutable. Create a separate processed table and save the processing script.

3. Choose the correct comparison unit

The comparison unit should match the claim.

• If the claim is about model behavior, group by model and avoid averaging different models into one thick line.
• If the claim is about benchmark difficulty, group by benchmark and explain why aggregating models is meaningful.
• If the claim is about a temporal process, plot progress over turns or percent progress and show trajectories, confidence bands, or small multiples.
• If the claim is about calibration or feasibility, show predicted feasibility against realized success or budget-to-finish.
• If the claim is about early stop-loss, use a cumulative curve: for each task, when did the model first correctly recognize infeasibility?

Decision rule: after every aggregation, ask, "What does this visual mark represent?" If the answer is awkward or scientifically vague, redesign the aggregation.

4. Pick the visual form

Use the simplest form that supports the claim.

Claim type	Preferred figure
One scalar per model or condition	Dot plot or table, not a low-information bar chart
Trend over progress or time	Line plot with percent progress on x axis and clear grouping
Distribution across tasks	Box, violin, strip, histogram, or empirical CDF
Relationship between two metrics	Scatter plot with careful sample-size annotation
Multi-factor comparison	Small multiples with shared scales
Budget saved or early stop-loss	CDF or survival-style curve over progress threshold
Dense appendix results	Structured tables or small multiples

Prefer tables when exact values matter more than visual pattern. Prefer small multiples when one panel would require too many colors, markers, or legends.

5. Encode uncertainty and sample size

Show uncertainty when the data has stochasticity or sampling variation.

Options:

• Confidence intervals or bootstrap intervals for group means.
• Standard error only when conventional for the audience and clearly labeled.
• Individual points plus a summary mark when the number of points is small.
• Sample-size bars or labels if group sizes vary, but only when the encoding is explained.

Avoid correlation coefficients or trend lines with very few aggregate points unless the statistical meaning is defensible. A correlation label such as r = 0.85 over five model points often creates more reviewer questions than insight.

6. Make the first glance obvious

Design for a reader who sees the figure with no conversation history.

Checklist:

• Replace decimals like 0.2, 0.4, 0.6 with 20%, 40%, 60% when the x axis is progress through a rollout.
• Rename vague labels such as Relative position to Task progress or Rollout progress.
• Rename jargon such as Average incremental tokens per turn excluding history to a shorter label like New tokens per turn and explain exclusions in the caption.
• Remove or explain every extra line, bar, shaded region, and marker shape.
• If there are two panels, the difference between left and right must be obvious from titles and shared labels.
• If a gray bar shows sample count, say so in the legend or annotation.
• Put the conclusion directly in an annotation when useful.

A useful review trick: show the rendered figure to a fresh model or collaborator with no context and ask, "What does this figure mean, and what is confusing?" Fix the first-glance failures before polishing style.

7. Manage attention

Use visual hierarchy deliberately.

• Highlight the primary comparison with color, line width, or annotation.
• Use muted colors for context and stronger colors only for the variables that matter.
• Use a consistent palette across the paper.
• Avoid rainbow colors unless hue itself encodes an ordered or categorical variable that must be distinguished.
• Use marker shape or line style for secondary encodings such as benchmark, and color for primary encodings such as model.
• Crop unused axis ranges when they waste space, but do not crop in a way that exaggerates effects.
• Remove chartjunk, redundant legends, unnecessary titles, and repeated labels in panel grids.

The figure should not make readers spend attention on color, layout, or decoration unless those elements encode the scientific point.

8. Fit the paper, not just the notebook

A figure that looks good in a notebook may fail in a two-column paper.

Before finalizing:

• Insert the figure into the paper draft at its intended width.
• Compare plot font size with caption and body text.
• Ensure axis labels, tick labels, legends, and annotations remain readable.
• Check that panel aspect ratios leave room for the caption and surrounding text.
• Prefer vector output (pdf or svg) for paper figures.
• Export raster images only when necessary, at 300 to 600 dpi.
• Save the exact script and command that produced the final figure.

If a figure consumes half a page, it must carry half a page of insight. Otherwise combine panels, simplify, or move it to the appendix.

Figure review rubric

Score each category from 0 to 2.

Category	0	1	2
Claim	No clear claim	Claim exists but is weak	One-sentence claim is obvious
Data integrity	Processing unclear	Mostly clear with gaps	Raw-to-plot path is reproducible
Aggregation	Misleading or unexplained	Defensible but not obvious	Matches the scientific question
Encoding	Confusing marks or legends	Understandable after effort	First-glance readable
Uncertainty	Missing when needed	Present but unclear	Appropriate and labeled
Attention	Distracting styling	Mostly clean	Visual hierarchy guides the reader
Manuscript fit	Too small or too large	Needs minor resizing	Readable in final layout
Caption	Repeats title or vague	Explains setup only	States setup, metric, and takeaway

A main-paper figure should usually score at least 13 out of 16. Appendix figures can be denser but still need reproducible data processing and readable labels.

Common red flags

Fix these before asking for aesthetic polishing:

• A thick average line across models when the claim is about each model.
• Averaging across benchmarks without explaining what the aggregate means.
• A binary-feasibility task without an intuitive binary success definition.
• A high score on a supposedly hard benchmark that has not been sanity-checked.
• A plot title that contains a full sentence but the caption does not explain the metric.
• Axis labels that require insider knowledge.
• Correlation statistics on a tiny number of aggregate points.
• Empty plot regions that dominate the panel.
• Font sizes that do not match the paper caption and body text.
• Colors that are more salient than the result.
• Multiple panels whose relationship is not explained.
• Appendix-level exhaustive results placed in the main paper.

High-level methodology for agents

When producing or revising a figure, keep the work at the methodology level before any implementation details:

1. Identify the single claim the figure should support.
2. Determine the experimental unit and the correct comparison unit.
3. Decide which raw-data transformations are scientifically necessary and explain them.
4. Choose a visual form that makes the comparison direct.
5. Specify uncertainty, sample size, and caveats.
6. Plan labels, legends, annotations, and caption so the figure is self-contained.
7. Check whether the figure belongs in the main paper, appendix, or internal analysis.
8. Review the rendered figure at final paper size and revise the design if the first-glance takeaway is unclear.

Do not start from plotting-code templates. Start from the scientific claim and only then choose whatever plotting implementation fits the project.

Captions

A caption should answer three questions:

1. What is plotted?
2. How was it computed?
3. What should the reader conclude?

Template:

Figure X: [Takeaway]. Each point/line/panel shows [experimental unit and grouping].
[Metric] is computed as [definition] over [sample size or task set]. Error bars/shading show [uncertainty].
The main pattern is [claim], suggesting [interpretation].

Avoid captions that merely restate axis labels.

When to stop

A figure is good enough when:

• The one-sentence claim is visible in the figure or caption.
• Every visual mark has a clear meaning.
• The aggregation matches the story.
• A fresh reader can explain the main takeaway without oral context.
• The figure is reproducible from raw data.
• It remains readable in the paper draft.