| name | figure-editing |
| description | Iterative polish of multi-panel publication figures. Patterns for long-lived layout-revision sessions where a human critiques each render. |
| user-invocable | true |
Figure Editing
This skill is intended for the middle/end game of figure production: many rounds of layout nudges against a human critic — move this up, shrink that, align these, swap a label. The bottleneck is iteration speed and prompt precision.
Generating from scratch? Load figure-formatting first for style rules. This skill is about the loop.
Principles
1. Make the inner loop fast
A 4-min render kills the session; 10 s lets you do 20 rounds quickly.
- Cache the data packet. One struct, one loader. For in-process iteration (IPython, notebook, long-lived session), a module-level dict is enough — no serialization. For CLI persistence across invocations:
.npz (numerical), zarr/h5 (mixed), richfile (complex Python structures). Avoid pickle. Populate functions consume packet slices, not raw sources. Provide --rebuild-packet when sources change.
- Draft mode.
--draft → PNG at 150 dpi, skip SVG/PDF/font post-processing. Final (600 dpi PNG + SVG + PDF with embedded fonts) runs only when settled. Warn when draft is on — stale PDF/SVG cause "this doesn't look right" confusion.
- Rasterize heavy elements. Thin alpha lines, dense scatter → raster. Fonts and structure stay vector. File size collapses.
2. Decompose independent units
When the artifact has separable parts (top/bottom, A–D vs. E–G, panel groups), give each its own standalone renderer + output file. Iterate each in isolation; merge at the end by porting settled values into a composite, or have the composite import and call each unit renderer.
plot_unit_top.py → figs/top.png
plot_unit_bottom.py → figs/bottom.png
plot_composite.py → figs/main.pdf # imports and calls both
Two agents can polish non-overlapping units in parallel. Note the sync step explicitly in handoff. When porting between different-size figures: y-offsets in fig-fractions rescale by height ratio; x-offsets transfer 1:1 only if widths match.
3. The human is the evaluator — single-pass edits only
A human-in-the-loop session wants short cycles, not perfect individual dispatches. The human sees the render and says what's wrong — don't simulate that loop inside an agent.
- One edit → one render → one Read → stop. No self-critique.
- When a change could go either way (inside vs. outside a panel, above vs. beside a label), pick one and move on. The user redirects if wrong. Over-asking slows the loop.
- Trivial tasks finishing fast is a clean result, not a waste.
- Exception: latitude tasks ("fix whatever overlaps X causes") allow 2–3 cycles with a summary of every change beyond the baseline.
4. Positional math in the prompt
Never "move it up a bit." Convert to fig-fractions yourself:
At 7.95" fig height ≈ 572 pt, 1 line of 8 pt text ≈ 0.014 fig-frac.
y_offset_F: 0.055 → 0.084 (move F up ~1 line).
Agents are excellent at mechanical edits and terrible at guessing proportions. Subagents start cold — anchor paths, current values, targets, and arithmetic in every prompt. Thin prompt → thin edit.
5. Explicit non-goals
Every dispatch lists what NOT to touch. Be concrete and named:
Non-goals: do NOT touch plot_composite(); do NOT rebuild the packet; do NOT run --final; do NOT change data or computed metrics; no critic loops.
Without these, agents wander into adjacent refactors.
6. Keep a ledger
Append per-round deltas to MEMORIES so the next agent knows current state and why:
## 2026-04-14 round 17
- y_offset_F: 0.055 → 0.084 (move F up 1 line)
- panel_C_height: 0.18 → 0.16 (shrink C to stop overlap with C's legend)
Re-dispatching the same nudge three times with nothing changing? The previous agent shifted the wrong variable, or not enough. Read current numeric state, then be explicit: "current shift is 0.055; you must end ≥ 0.130."
Dispatch template
→ <role> (<model>) | skills: workspace-conventions, coding-style | task: <one line>
Current state: param_A = 0.055, param_B = 0.031.
Goal: param_A → 0.084 (X up 1 line), param_B → 0.022 (Y down 0.3 lines).
At <fig height> in., 1 line ≈ <K> fig-frac.
One edit → one --draft render → one Read → report.
Non-goals: …
Response shape: ≤80 words, file:line refs, final PNG path.
Sharp edges
hspace doesn't tighten rows with set_box_aspect. Use ax.set_position([...]) after canvas.draw().- Concurrent edits to overlapping code. Same file is fine if the functions are disjoint; serialize if they collide.
- User steers from a stale render. Surface the discrepancy, don't silently follow.
- Mid-task status messages ("let me wait..."). Require the final message be the deliverable.
- Decide whether to read the PNG after each render. Catches cutoffs/overlaps even in single-pass mode.
