Use when the user has scientific data (or a prompt alluding to scientific data) and wants a publication-quality figure made from it. A generator drafts and renders a figure that lands a frozen communication goal; an adversarial critic critiques it hard and grades it 1-5 per axis against a fixed rubric (message, aesthetic, clarity, integrity, and a conditional domain-completeness axis), aggregates to 0-100, and decides pass; the generator revises against the critic's findings until the grade clears a threshold or the budget is hit. Both roles may consult the literature (Semantic Scholar + arXiv) to verify domain content (e.g. a pathway figure's gene set, or a benchmark's reported numbers), and conform to / grade against a named journal's figure spec fetched via web search. Not for writing a paper or analyzing a dataset, and not for editing an existing finished image — this renders a figure from data/brief and iterates on it.
Use when the user has scientific data (or a prompt alluding to scientific data) and wants a publication-quality figure made from it. A generator drafts and renders a figure that lands a frozen communication goal; an adversarial critic critiques it hard and grades it 1-5 per axis against a fixed rubric (message, aesthetic, clarity, integrity, and a conditional domain-completeness axis), aggregates to 0-100, and decides pass; the generator revises against the critic's findings until the grade clears a threshold or the budget is hit. Both roles may consult the literature (Semantic Scholar + arXiv) to verify domain content (e.g. a pathway figure's gene set, or a benchmark's reported numbers), and conform to / grade against a named journal's figure spec fetched via web search. Not for writing a paper or analyzing a dataset, and not for editing an existing finished image — this renders a figure from data/brief and iterates on it.
compatibility
Requires Python 3.9+
metadata
{"version":"0.1.0"}
Scientific Figure Loop
The artifact is a scientific figure (the rendered image + the plot.py that produces it). Each
iteration generates → critiques+grades: a generator authors a rendering script and renders the
figure to land the frozen <goals> message; an adversarial critic grades it 0-100 against the fixed
rubrics/rubric.md and decides pass; the generator then revises against the critic's concrete
findings. The loop runs until the grade clears <pass_threshold> or the budget is hit. All work
happens on copies inside a sandbox; the user's data is copied in read-only and never edited.
The cast (all in this folder):
roles/generator.md — drafts/revises plot.py, renders figure.png by running <render_cmd>,
optionally grounds domain content via <lit>; writes generation_notes.md.
roles/critic.md — the adversarial grader: re-derives each rubric axis independently, spot-checks the
figure's numbers against the data, optionally lit-checks domain completeness, and emits
schemas/critique.schema.json (the grade + pass + executable findings).
rubrics/rubric.md — the fixed grading rubric (the critic never edits it).
schemas/critique.schema.json — the one validated output.
Spawn-or-degrade. On Claude Code, spawn the generator then the critic as real Agent subagents
(sequential — the critic needs the generator's figure); otherwise adopt each role inline. You are the
orchestrator.
Why the critic grades itself (the honesty problem)
The critic both critiques and grades, which under loop-termination pressure invites inflation and a
generator that games the rubric. roles/critic.md + rubrics/rubric.md counter this: the critic (1)
applies a fixed rubric it never edits, (2) re-derives each axis from the rendered figure + data +
frozen <goals> rather than echoing the generator, (3) recomputes a sample of the figure's numbers
itself instead of trusting "it's fixed", (4) holds a fixed, anchored bar with no credit for effort
or elapsed iterations, and (5) applies hard gates (a figure value that contradicts the data, a
misleading axis, or fabricated data presented as real fails the figure regardless of the average). The
generator optimizes the concrete findings; the critic grades holistically against the frozen goal — so
"address every finding" does not mechanically buy a pass. Because the two are separate agents, the critic
never just rubber-stamps the generator's intent.
When to use
Use when scientific data (or a prompt describing it) exists and the user wants a polished figure pushed
past a quality bar with adversarial critique and a graded rubric. Default: run the full
generate→critique loop below. Escape hatch: if the user only wants one figure + a critique (no
iterating), run one generate + critic pass and stop. Not for writing a paper or doing the analysis, and
not for retouching an already-final image.
Setup
Resolve bindings interactively. If loop.run.yaml exists in the working dir, load it, confirm the
values in one line, and skip to the loop. Otherwise: on Claude Code (the AskUserQuestion tool is
available) infer a likely value for each binding and present it as the recommended option; on other hosts
ask each as a quoted plain-text prompt. Then write loop.run.yaml (format: examples/run.example.yaml)
and confirm every value — including the distilled <goals>, whether a journal spec applies, and the
live/degraded literature tier — before creating any other files.
binding
meaning
default
how to infer
<brief>
the prompt describing the figure to create + the message/claim it must communicate (and, if data exists, what the data represents)
—
the user's request; if pasted as prose, save to <sandbox_root>/brief.md
<data_paths>
data file(s) the figure visualizes (CSV/TSV/parquet/JSON…); empty → an illustrative/schematic figure (the integrity axis then checks internal consistency, not data fidelity)
—
scan the working dir near the request; may be null
<goals>
the figure's communication objective(s), 1-3 bullets — frozen; the critic grades against these and the generator may never abandon them
—
distill from <brief> at setup, confirm with the user in one line
<render_cmd>
command/interpreter that runs the plot script the generator writes (it appends iter<N>/plot.py), in the user's env — the skill ships no plotting deps, the same contract as scientific-writer's <plot_command>
python3
pyproject.toml/.venv/README; e.g. uv run python or a venv python
<style>
optional aesthetic/style guide or a named target journal/venue — when a journal is named, its figure spec is fetched at setup (see below) and both roles conform to / grade against it
—
ask the user; check <brief> for a venue
<pass_threshold>
overall_score (0-100) the critic must reach (and no hard gate) to stop
85
a polished, publication-ready figure without demanding perfection
<budget>
max iterations
6
—
<patience>
stop after this many consecutive no-improvement iterations
2
—
<sandbox_root>
where the plot scripts, figures, critiques, and the ledger live
./sandbox
—
The domain axis is not a binding — the critic auto-detects whether the figure makes an external
domain claim (a named pathway, gene set, canonical benchmark, taxonomy, mechanism, or a literature-
established number) and activates the domain axis itself; no user toggle.
Literature toolchain (optional, S2 + arXiv only). Domain grounding goes through the sibling
literature-search skill — resolve <lit_skill_dir> (it installs as a sibling, e.g.
~/.claude/skills/literature-search/), <lit_py> = python3, and <lit> = <lit_skill_dir>/tools/lit_search.py; append --cache-dir <sandbox_root>/literature/.cache after a
subcommand to reuse the cache. Use only the keyless S2 + arXiv core (<lit> search default
--source s2, snippet, cite, fulltext); do not use --source openalex|both, ask, or
bgpt. Confirm <lit> --help works at setup; if the skill is absent, degrade all retrieval to
WebSearch/WebFetch. Record the tier (presence only) in loop.run.yaml.
Reuse what you've already pulled — don't re-query every iteration. Every retrieval is cached under
--cache-dir <sandbox_root>/literature/.cache, and each role appends the facts it establishes (claim →
number/element → source) to <sandbox_root>/literature/sources.md. Both roles consult that record (and
the cache) first and only fetch papers/snippets not already on hand; a value a prior iteration already
verified is re-checked by re-reading its recorded source, not by re-searching from scratch. The point of
the literature step is correctness, not call volume — once a paper is pulled, work from it.
Journal style sheets (separate path, via web search). When <style> names a journal/venue, fetch its
figure guidelines once at setup via WebSearch/WebFetch → <sandbox_root>/style/journal_spec.md
(column width in mm, minimum font size, fonts, line weights, color mode, panel-label convention, file
requirements). Both roles read this single cached spec — the generator conforms, the critic anchors
its aesthetic/clarity axes to it — so the two never grade against divergent specs. This is distinct from
<lit>: web search finds the journal's style spec; <lit> (S2/arXiv) checks domain content.
Environment. The generator renders figures by running <render_cmd>in the user's own
environment — that code needs third-party deps (matplotlib, pandas, …), so the skill ships none and
never installs them; it shells out to <render_cmd> and reads the rendered figure.png. PNG is rendered
so the critic can view the image (an SVG would be read as XML). The deliverable is figure.pngplus its
plot.py — the reproducible source the user re-renders to any vector format. Any helper code the skill
writes stays stdlib-only.
Initialise the sandbox once bindings are confirmed (copy the data in read-only; never edit originals):
<sandbox_root>/
├── loop.run.yaml ← resolved bindings + <goals> + literature_tiers
├── brief.md ← <brief> (if pasted as prose)
├── ledger.tsv ← header only (see Ledger)
├── data/ ← read-only COPY of <data_paths> (omit if no data)
├── style/journal_spec.md ← fetched journal figure spec (omit if no journal named)
├── literature/.cache/ ← lit_search on-disk cache
└── iter1/ ← created by the generator
├── plot.py
├── figure.png
├── generation_notes.md
└── critique.json
The loop
<N> starts at 1. Unlike loops that grade an existing baseline, the generator runs first every
iteration (there is no input figure to critique) — iteration 1 drafts from scratch, iterations 2+ revise.
Re-grade fresh every iteration: the score comes only from a new critique of the current figure, never
carried over. Surface-only changes won't move it.
Copy this checklist and tick items off:
Generate — spawn generator (roles/generator.md) with <brief>, <data_paths>, <goals>,
<style> (+ style/journal_spec.md), <render_cmd>, <lit>, and — on iter 2+ — iter<N-1>/critique.json.
It writes/edits iter<N>/plot.py, runs <render_cmd> iter<N>/plot.pyinside the sandbox to render
iter<N>/figure.png, grounds any domain content via <lit>, and writes iter<N>/generation_notes.md.
Critique + grade — spawn one freshcritic (roles/critic.md) over iter<N>/figure.png +
the data + <goals>, applying rubrics/rubric.md: it re-derives each axis 1-5 independently,
spot-checks the figure's numbers against the data, optionally lit-checks domain completeness, computes
overall_score = 100 × Σscore / (5 × n_axes), applies hard gates → pass, and writes
iter<N>/critique.json (validates against schemas/critique.schema.json).
Log — append one ledger.tsv row (see Ledger).
Stop check — critique.pass == true, or N == <budget>, or overall_score flat for
<patience> iterations → stop (see Stops).
N = N + 1 and repeat (back to Generate, which now revises against the critique).
A critique looks like (abridged; full shape in schemas/critique.schema.json):
{"iteration":2,"summary":"Needs revision: honest now, but the MAPK panel omits ERK and the y-axis lacks units.","axes":{"message":{"score":4,"justification":"Up-regulation reads clearly."},"aesthetic":{"score":3,"justification":"Palette not colorblind-safe (red/green)."},"clarity":{"score":4,"justification":"Y-axis missing units."},"integrity":{"score":4,"justification":"Bar heights match data/levels.csv."},"domain":{"score":3,"justification":"MAPK cascade missing ERK node."}},"overall_score":72.0,"pass":false,"gate_failures":[],"spotchecks":[{"target":"group-B bar = 2.4","method":"recomputed from data/levels.csv","result":"confirmed"}],"findings":[{"urgency":"must_fix","action_type":"add","area":"domain:incomplete","finding":"MAPK cascade panel omits ERK1/2 downstream of MEK.","proposed_action":"Add ERK node + MEK→ERK edge.","target_artifact":"iter2/plot.py","evidence":"lit snippet: canonical MAPK = RAF→MEK→ERK"}]}
Ledger
<sandbox_root>/ledger.tsv, tab-separated, never commas in free text:
Use - in the domain column when the domain axis is inactive (n_axes=4). The per-iteration
critique.json and generation_notes.md live in iter<N>/. Report the best-scoring iteration when
stopping on budget/plateau, not necessarily the last. Leave the sandbox untracked.
Constraints
Never edit or run anything outside <sandbox_root> — data is copied in read-only at setup; the
generator's plot.py and <render_cmd> run from the sandbox; no ../ escapes.
Never fabricate data, numbers, or domain elements. A figure presented as real data must render from
<data_paths>; with no data, the figure must read as clearly illustrative/schematic, not a fake data
plot. Domain content (genes, nodes, baselines, reported numbers) added from <lit> comes from a real
retrieval that iteration, never invented.
The grading bar is fixed and reproducible — the critic never relaxes a rubric anchor to let the
loop finish; a confirmed hard gate fails the figure regardless of the average.
Protect <goals> — the generator makes the same message prettier and clearer; it never drops or
distorts the intended message to chase a higher score.
One coherent revision batch per iteration, blocks/gates first, so score moves are attributable.
No installs — the skill ships no plotting deps; <render_cmd> runs in the user's env, helper code
is stdlib-only; literature is the keyless S2 + arXiv core only. Never print or commit API keys
(keys.env stays gitignored).
Stops
The loop stops on the first of:
Pass — critique.pass == true. Report the deliverable (iter<N>/figure.png + plot.py), the
score, and the trajectory.
Budget — N == <budget>. Report the best-scoring iteration as the deliverable.
Plateau — overall_score flat for <patience> iterations. Report the best iteration + the
standing gate_failures/must_fix blockers.
Always end with the deliverable (iter<N>/ path), its overall_score and pass/fail, the per-axis
scores, the score trajectory from ledger.tsv, and — if it did not pass — the standing blockers
(gate_failures + open must_fix) between the figure and the bar.
