/paper-figures

name: paper-figures
description: "Use this skill to produce standalone, publication-ready PNG graphics and reproducible matplotlib scripts from tabular data (CSVs or DataFrames). This tool is built specifically for rendering numerical data into formal scientific visualizations—including scatter, line, bar, pie, ring, bubble, tornado, KDE, violin, box, heatmap, histogram, and area charts, plus composite multi-panel figures that combine these types in a single image—for scholarly manuscripts. Only trigger this skill when the final deliverable is an individual image file. Do not use this skill for interactive dashboards or HTML-rendered outputs (Plotly, Streamlit, Quarto, Jupyter notebooks), nor when the request involves building a container document or presentation that includes charts (slide deck, conference poster). Finally, it is not for non-data conceptual illustrations like flowcharts, algorithm schematics, or process diagrams. This skill focuses on high-fidelity data rendering into final image files, not presentation design, document layout, or reverse-engineering code from existing screenshots."
allowed-tools: "write_file edit_file read_file think_tool execute"
metadata:
  author: EvoScientist
  version: '0.1.0'
  tags: [core, figures, visualization, academic-writing]

Paper Figures

A structured approach to producing publication-ready chart figures (PNG) from tabular data plus a natural-language description, using matplotlib.

When to Use This Skill

• User provides a CSV / dataframe / inline data and asks for a chart
• User describes a target figure in words and wants it rendered
• User mentions "figure", "plot", "chart", "visualize", "render" for a paper or experiment

---

Inputs and Output

**Inputs the agent will receive:**

• A **data source**: CSV file path, JSON, or inline table.
• A **description**: natural-language text specifying chart type, axes, title, colors, annotations, legend, scenarios, etc. Sometimes terse, sometimes a full paragraph. The description is the full specification — no reference image is provided.

**Output (always):**

• A standalone Python script `plot.py` that:
• Loads the data from the provided source
• Renders the figure with `matplotlib`
• Saves a PNG via `plt.savefig(..., dpi=300, bbox_inches="tight")`
• The rendered `plot.png` next to it (the script is **run** and the PNG produced — do not stop at the script).

**Verification artifacts (write when filesystem access is available):**

• `figure-spec.md` — the compact figure specification extracted before coding.
• `audit.md` — the post-render audit checklist and any repairs made.
• `final-status.md` — one visible status label: `PASSED`, `PASSED_WITH_WARNINGS`, `REPAIRED`, or `FAILED_NEEDS_HANDOFF`.

**Output directory:**

• If the user specifies an output directory (e.g. "save to `path/to/dir/`"), write `plot.py` and `plot.png` inside that directory. Create the directory if it does not exist.
• If no directory is given, write to the current working directory.
• The two filenames are always `plot.py` and `plot.png`. Repeated runs on different inputs go to **different directories**, not different filenames — this keeps the script reference inside the PNG's neighbourhood stable and makes batch comparison easy.

---

Core Workflow

Step 1: Plan Figure        -> verify: description/data ambiguity handled
Step 2: Extract Spec       -> verify: figure-spec.md has all required fields
Step 3: Implement          -> verify: plot.py runs and plot.png exists
Step 4: Audit Figure       -> verify: chart matches spec, data, and description
Step 5: Repair or Finalize -> verify: final-status.md is honest

Treat the workflow as a small validation protocol, not a one-shot drawing task. The chart is done only after the audit passes or after you explicitly mark the remaining gap.

Status Labels

Use exactly one final status:

| Status | Meaning | |---|---| | `PASSED` | The figure matches the requested chart type, data fields, scales, labels, series, legend, annotations, and output contract. | | `PASSED_WITH_WARNINGS` | The figure is usable and faithful to the request, but a minor style/layout mismatch remains and is named in `audit.md`. | | `REPAIRED` | The first render failed at least one audit item, the script was revised, and the repaired render now passes. | | `FAILED_NEEDS_HANDOFF` | A required field, chart semantics, package dependency, or visual requirement could not be verified or repaired. Name the exact blocker. |

Do not award `PASSED` because the script ran. Running only proves the PNG exists; it does not prove the figure matches the request.

Step 1: Plan Figure

Before writing any code, identify from the description:

• **Chart type** (line, bar, scatter, pie, KDE, violin, bubble, tornado, ring, heatmap, …). If ambiguous, prefer the type explicitly named; otherwise infer from the axes/data shape.
• **Axes**: x-label, y-label, units, scale (linear/log), tick formatting. Watch for **shared axes** across subplots, **twin axes** (`ax.twinx()` / `ax.twiny()`) when two series share an x but have different y-units, and **dual / broken axes** when ranges span very different magnitudes.
• **Title**: use the title verbatim if quoted in the description.
• **Series / categories**: how many, names, ordering.
• **Colors**: any specific colors named (use them); otherwise apply the default palette.
• **Annotations**: legend, gridlines, reference lines, data labels.

If the description references quantities ("around 200", "just above 0"), use those as sanity checks against the CSV — descriptions are paraphrased, the CSV is authoritative.

A few patterns that show up repeatedly:

• **Title context for cross-sections**: if the data is a snapshot (a single year, a single experiment), put that context in the title itself — as a parenthetical, comma-separated suffix, or quoted prefix. Don't add a separate "subtitle" via `fig.text` or similar; matplotlib has no clean subtitle API and ad-hoc s