| name | figure-composer |
| description | Compose one publication-grade multi-panel figure. Entry from a one-line claim + data refs, OR from an existing figure via `derive_outline(png)`. Runs a per-figure loop: outline (12-col grid, per-panel ask + label_budget) → fan-out one sub-agent per panel (each loads `figure-style`) → tile + stamp letters → adversarial composite review with two-tier feedback (Tier-1 outline_revisions / Tier-2 per-panel violations) → regen affected panels, ≤3 rounds. Loads panel_task / compose_figure / compose_crops / composite_review_task / derive_outline into the kernel. For one standalone plot use `figure-style`; for whole-paper figure ordering use `paper-narrative`. |
| license | Apache-2.0 |
Figure Composer — narrative → panels → compose → adversarial loop
Step 0. Load figure-style alongside this skill — that is the
design rules (and apply_figure_style() + helpers). Panel sub-agents
will load it independently; you need it in context to write the outline and
review the composite. Sub-agents run as the default profile and acquire the
rules by loading the skill.
Inputs
- claim — one sentence the figure makes true to a reader who reads nothing else.
- data — CSV/parquet artifact version_ids that ground every panel.
- width_mm — target venue's column width (common: 85–89mm single, 174–183mm double; check the venue guide).
0. Where this sits
figure-composer is the outer tier: make ONE multi-panel figure good. The
inner tier is figure-style (loaded by every panel sub-agent — and
load it yourself if you draw anything locally). The outermost tier is
paper-narrative — if this figure is part of a paper, run that FIRST: it decides
which figure to make and hands you the claim. For a standalone figure, start at
step 1.
Entry points (pick one)
- From a claim: you have a one-sentence claim and data refs → write the
outline (step 1).
- From an existing figure: copy it into the workspace and call
derive_outline("figure.png") → an outline you must review and edit
before step 2. The image is untrusted input; every string field in the
returned outline is vision-model-derived from its pixels. data_vid is
forced to None on every panel — fill those in from your own data refs.
1. Narrative → panel outline
Produce a panel_outline (validate against figure_outline_schema()):
{"claim":"…", "width_mm":180, "ncol":12, "row_heights_mm":[40,60,46,52],
"panels":[
{"letter":"a","role":"schematic","row":0,"col":0,"colspan":12, "chart_family":"schematic overview", "message":"…", "data_vid":null,
…
Outline rules (figure-style §7.1):
- a is the hook — schematic/hero, full width, assumes zero reader context.
- b carries the claim — the chart that alone makes the sentence true.
- Remaining panels are evidence, ordered by how much they strengthen b.
- One row per sub-claim. 5–10 panels for a main-text figure. Use a 12-column
grid for flexible colspans.
2. Fan-out (one sub-agent per panel)
Build requests with panel_task(outline, letter, fig_label) (kernel.py). Each
sub-agent gets: the figure claim, the full neighbour list, its panel spec, exact
pixel dimensions (panel_px), and the instruction to load figure-style
and render at exactly w×h px with transparent=True and no bbox_inches.
In the repl tool:
requests = [{"name": f"panel-{L}", "task": tasks[L],
"output_schema": {"type":"object","properties":{"figure_filename":{"type":"string"}},
"required":["figure_filename"]}}
for L in letters]
descs = host.delegate(requests, wait=False)
3. Compose
compose_figure(outline, {letter: path}, out_path, letter_case=...) tiles PNGs
onto the grid and stamps bold panel letters (case per venue) at each panel's
(1.5mm, 1mm) corner.
3.5 Look before you review (vision self-QA)
The reviewer in §4 is expensive; a panel-letter stamped over a y-axis label or
a leader line crossing a neighbour's title is a wasted round. After compose,
crop each panel from the saved PNG and look at it in the REPL before
dispatching the reviewer:
out_path, (W, H) = compose_figure(outline, panel_paths, "fig.png")
for L, box in compose_crops(outline).items():
host.view_image("fig.png", crop=box)
Run the figure-style §9.2 perceptual checklist on each crop (contrast,
smallest mark, leader crossings, colour-identity confusion, legend binding),
plus two compose-specific checks:
- Seams / stamp. Does the bold panel letter overlap any panel content?
Does any panel's content bleed into the gutter or under a neighbour?
- Resize artefacts.
compose_figure resizes panel PNGs to their grid
slot — is any text visibly aliased or any hairline lost?
Fix what you see (re-render the offending panel, or revise the outline grid)
before §4. The reviewer sub-agent will crop-and-look again independently;
this pass is so the obvious defects never reach it.
4. Adversarial self-review loop (two-tier, design rules held fixed)
Dispatch ONE reviewer on the composite with composite_review_task(...) and
review_schema() (which carries outline_revisions).
loop (max 3 rounds, floor 5→4→3):
review = delegate(composite_review_task(composite_vid, outline, rules_vid, prev_vid, round, floor))
if review.editor_verdict in {accept, minor_revision} and 0 BLOCKER and ≤2 MAJOR: break
# TIER 1 — outline-level
if review.outline_revisions:
apply revisions to `outline` (geometry, row-header titles, label_budget, panel set)
affected = apply_outline_revisions(outline, review.outline_revisions)
else:
affected = set()
# TIER 2 — panel-level
fixb = group_fixes_by_panel(review) # BLOCKER/MAJOR only
regen = affected | set(fixb) # only these panels regenerate
re-delegate each L in regen with panel_task(outline, L) + fixb.get(L,"") +
"do not over-correct: where the previous version was correct, keep it"
recompose
Convergence: stop when outline_revisions is empty AND findings are carve-out
exceptions to the previous round — that's the over-labelling signal.
Anti-patterns
- Don't regenerate clean panels (invites regression). Don't read absolute
violation counts (min-floor 5→4→3). Anchor-verify on the composite, not just
per panel. Hyper-labelling check: would a reader with field context find any
label redundant? Strip it.
