paper-figures

name

paper-figures

description

Create, audit, and improve figures in systems papers. Covers both design diagrams (architecture, flow, component) and result plots (bar charts, line plots, heatmaps). Checks figure-text alignment, abstraction level, claim support, and visual clarity. Use when the user says "draw an architecture diagram", "make a figure", "check the figures", "improve the plots", or when iter-refine-writing flags a missing diagram. Design diagrams use TikZ or draw.io; result plots are always drawn with Python (matplotlib).

Paper Figures

Create and audit figures for systems papers. Two types of figures have different rules — read the corresponding reference before creating or reviewing.

Do not perform any Git operation. Return figure, source, and report changes to the caller.

First Step

Determine the figure type:

• Design diagram (architecture, flow, component, trust boundary) → read references/design-diagrams.md
• Result plot (bar chart, line plot, CDF, heatmap, table-as-figure) → read references/result-plots.md

If auditing existing figures, read both references and check every figure in the paper.

Audit Checklist (for all figures)

1. Does every figure support a specific claim? Identify which claim in the text the figure supports. If no claim, the figure may be unnecessary.
2. Is the figure referenced in the text? Every figure must have a \ref{} in the prose that explains what the reader should see.
3. Is the caption self-contained? A reader should understand the figure from caption alone without reading the body text.
4. Do labels match the text? Component names, axis labels, and legend entries must use the same terms as the prose.
5. Is the abstraction level correct? Design diagrams in the Design section should be mechanism-agnostic. Implementation details belong in Implementation section figures.
6. Does each RQ use the right evidence format? Comparisons, trends, distributions, and scaling behavior normally need a plot (bar/line/CDF/heatmap). Tables are appropriate when exact values, feature matrices, correctness cases, or many discrete configuration dimensions are the evidence. An RQ with only tables is a review trigger, not an automatic defect: state why exact lookup matters more than visual shape.
7. Avoid redundant floats. Within one RQ, do not present the same data as both a table and a figure unless the two artifacts serve distinct reader tasks, such as a main-text trend plot plus an appendix table of exact reproducibility values. When one artifact suffices, pick the format that best serves the claim and use annotations or prose for a small number of exact values.

Figure–Text Coordination

When a figure is present, the surrounding prose and the figure each have a distinct job. Violations of this split are the most common source of redundancy and unclear evaluation sections.

• Prose defines metrics before the figure. Before referencing a figure, the text must explain what each axis, metric, and label means — what "mixed weight %" measures, what a "unique stack" counts, what each x-axis category represents. A reader who has not seen the figure should understand the experimental setup from the text alone.
• The figure shows the data; the prose interprets trends. Once the figure is referenced, the text should state the takeaway ("prompt tags are the decisive axis") and explain why ("because sessions contain multiple intent phases"), not restate numbers the reader can already see in the annotated bars or data labels. Concrete numbers in prose are acceptable only when they are not visible in the figure (e.g., p-values, counts not plotted) or when a single key number anchors a claim that the figure alone does not make obvious.
• Captions are self-contained. A reader skimming figures should understand what the figure shows from the caption alone — include the dataset size, what the axes/bars/lines represent, and the one-sentence takeaway. Do not require reading the body text to decode the figure.
• Labels in the figure must match the terms used in prose. If the text says "mixed weight percentage," the legend must not say "Mixed %" without prior definition. Axis labels, legend entries, and bar annotations use the same vocabulary as the surrounding paragraphs.

LaTeX Placement Mechanics

Figure content and figure placement fail independently — check both. For two-column papers:

• Wide figures span both columns: use figure* (and table*); a wide figure squeezed into one column is unreadable. figure* cannot use [h]; it floats to the top of a page.
• Side-by-side needs a width check: two subfigures sharing one column are usually too small to read. If labels drop below ~7pt effective size, stack them or promote to figure*.
• Default to [t] placement; [h] fights LaTeX and loses.
• Pinning a figure to a specific page (e.g. architecture figure on page 2): place the float's source just after the first paragraph of the page-2 content, use [t!], and let text (even a citation-heavy paragraph) flow to the next page instead — text can move, the figure anchor should not. Verify the final PDF page after every recompile that touches floats.
• After any float change, recheck page budget and margins — floats are the usual cause of text-height overflows.

Result Plots Are Python-Drawn

Every numeric/result figure — RQ figures, bar charts, line plots, CDFs, heatmaps — is generated by a Python script (matplotlib) that reads the result data files. Never pgfplots, never hand-placed TikZ coordinates, never numbers typed into the figure by hand: if a value changes in the results, rerunning the script must regenerate the figure. Keep the script and its data paths in the repo next to the figures so any plot can be reproduced; LaTeX includes the generated PDF/PNG. TikZ and draw.io are for design diagrams only.

Creating Figures

When creating a new figure:

1. Read the relevant reference file
2. Ask: what claim does this figure support?
3. Draft the figure (TikZ/draw.io for design diagrams; a Python matplotlib script for result plots, per the rule above)
4. Check against the reference's checklist
5. Write a self-contained caption
6. Add \ref{} in the text where the figure is discussed
7. Compile and verify page count