visual-iteration

name

visual-iteration

description

Iteratively refine any visual output — charts, plots, web UIs, diagrams, slides, 3D renders — by rendering it to an image, actually looking at the image, critiquing it against the goal, and editing until it converges. Use when output quality is judged by eye ("make it look right", "fix the layout", "the legend covers the data", "polish this chart/page/diagram") or whenever generating visual output whose first attempt is unlikely to be final.

Visual Iteration

Code that produces visuals is almost never right on the first render. The failure mode this skill prevents: editing plotting/layout code blind, declaring it fixed, and being wrong. The rule is simple — never claim a visual is correct without having looked at the rendered image in the same turn as the claim.

The loop

Copy this checklist and track progress across iterations:

Visual Iteration Progress:
- [ ] 1. Establish the goal (explicit criteria from the request + defaults)
- [ ] 2. Render to an image file (iter-01.png)
- [ ] 3. View the image and critique against the goal
- [ ] 4. Edit source to fix the top problems
- [ ] 5. Re-render to a NEW file (iter-02.png, iter-03.png, ...) and re-view
- [ ] 6. Converged? Compare final against iter-01 and report what changed

1. Establish the goal

Write down 2–5 concrete acceptance criteria before rendering anything. Split them into:

• Stated criteria — what the user literally asked for ("legend must not cover the plot", "start the x-axis mid-April"). These are non-negotiable.
• Baseline criteria — always apply even if unstated: nothing clipped or overlapping, text legible at intended viewing size, no unlabeled axes/series, sensible use of space, consistent styling. The full list is in references/critique-rubric.md.

2. Render to an image

Render the artifact to a PNG on disk. Exact commands per medium (matplotlib, HTML/web page, Mermaid, LaTeX/TikZ, SVG, React component, terminal UI) are in references/render-recipes.md — read it the first time you render a medium in a session.

Conventions:

• Number every render: iter-01.png, iter-02.png, … in a scratch directory. Never overwrite — the numbered history is what makes before/after comparison and regression detection possible.
• Render at the size it will actually be viewed (a chart destined for a slide needs a slide-sized render; a mobile page needs a 390px-wide viewport). A visual that looks fine at the wrong size proves nothing.

3. View and critique

Open the PNG with whatever image-viewing capability your harness has (in Claude Code, the Read tool renders images) — actually look at it. Then critique in two passes:

1. Against the stated criteria — check each one explicitly, pass/fail.
2. Against the rubric — scan references/critique-rubric.md for defects the user didn't mention but will notice.

Write the critique down as a ranked defect list (worst first) before touching code. Naming the defects before editing prevents the classic drift where the edit fixes one thing and silently breaks another.

4. Edit

• Far from the goal (≥3 significant defects): batch-fix them all in one edit pass.
• Close to the goal (1–2 defects, or polishing): change one thing at a time. Small visual systems are coupled — a legend move changes usable plot area, a font bump reflows a layout — and single changes keep cause and effect attributable.

5. Re-render and re-view

New numbered file, view it, re-run the critique. Explicitly check that previously-passing criteria still pass — visual regressions are the most common failure in this loop. If a defect survived the fix, do not repeat the same edit harder; diagnose why it survived (wrong element targeted, style overridden elsewhere, stale cache/build) before editing again.

6. Converge and stop

Stop when either:

• All stated criteria pass and no rubric defect of severity "user would notice" remains — done; or
• Two consecutive iterations produce no measurable improvement — stop and present the best iteration with the remaining defects named, rather than thrashing. Diminishing-returns polishing beyond ~5–6 iterations is rarely worth it unless the user asked for pixel-perfect.

When done, view the first and final renders side by side and report: iterations used, what changed, and any criteria you could not satisfy (with why). Send the final image to the user.

Rules

• Never assert visual correctness from code inspection alone. Render and look, every time.
• Never overwrite iteration files; the numbered trail is the audit log.
• A render that errors or produces an empty/blank image is iteration feedback too — read the error, don't just retry.
• If the medium can't be rendered headlessly in this environment (no display, missing renderer), say so and fall back to the closest renderable proxy (e.g. static export of an interactive chart) rather than skipping the look-at-it step.