design-iteration

name	design-iteration
preloaded	true
description	Improve design mockups from critique (design-review, user studies, a multi-perspective council, a UI lint pass, or raw notes): triage keep/change/kill, produce a new version with a per-change rationale trail so the next test can measure improvement. If no critique exists yet, runs the full test-iterate-test loop (review + studies + lint) around the mockup. Reaches for a design system if one exists. Use when: run design-iteration on this mockup, iterate on these designs, revise the mockups from feedback, incorporate the review, next design iteration, close the loop on design feedback.

Design Iteration

The loop step between testing a design and re-testing it. Something else generated the feedback (a design-review, a marketing-psychology / persuasion review, an another-perspective council, a synthetic-userstudies run, a UI-lint report, or the user's own notes). Your job is to turn that feedback into a revised version without losing the plot: every change is traceable to the critique that drove it, so the next test can measure improvement instead of just noticing the design changed.

Two ways to invoke this skill

Node mode (default): critique already exists (the user pastes a review, or a prior step produced one). Go straight to The loop below: triage → revise → change log. This is the single-responsibility core.

Full-loop mode: the user points at a raw mockup with no critique yet, e.g. "run design-iteration on this mockup / on <url>". There's nothing to triage yet, so you orchestrate the whole test-iterate-test pipeline: generate the critique (by invoking the sibling test skills), run the iterate node between each, and polish at the end. You still only own the iterate node. The review, study, and lint are separate skills you call; this skill never reimplements their logic. If you catch yourself writing a heuristic scorecard or a persona interview inline, stop, that's the sibling skill's job, invoke it.

Full-loop pipeline (the proven order)

Run these in sequence. Each → iterate is a pass of this skill's core loop on whatever the prior step produced.

1. Reach for the design system (step 3 below) so critique isn't distracted by off-brand noise. Apply it loosely up front; save strict conformance for the end.
2. Generate critique in parallel — dispatch design-review + a marketing-psychology / persuasion review + another-perspective as concurrent subagents against the artifact. They're independent, so fan them out in one batch, don't serialize.
3. → iterate (pass 1) on the combined critique. Triage keep/change/kill, revise the winners in the real source, emit the change log.
4. synthetic-userstudies (Variant Panel Mode) on the revised artifact: 4-6 personas weighted to the real leaking segment, adversarial ones included, one subagent per persona.
5. → iterate (pass 2) on the panel. Convergence only: an issue 2+ personas hit independently earns a fix; a single persona's taste complaint does not. Calibrate to the real audience, don't let the most fragile persona over-drive fixes (see synthetic-userstudies for the false-floor rule).
6. A final UI-polish pass on the survivor: motion/timing, tap targets (44px floor), contrast (WCAG AA), typography, using a dedicated lint/polish skill if you have one. Verify computed contrast/size numerically, don't eyeball.
7. Deploy + verify live, then emit a final summary tracing the whole arc.

Full-loop gotchas (learned the hard way)

• Toolset names for subagents are exact: browser, terminal, file, skills, web, vision. Invented names like BrowserControl or ShellExec are silently dropped and the child launches tool-less and fabricates its transcript. If a review comes back with no real tool trace, discard and re-dispatch with correct names.
• Never fabricate a test result. If a subagent couldn't reach the URL or a tool 502'd, it says so; you re-dispatch or note the gap. A plausible-looking made-up persona reaction is worse than a missing one.
• Verify objective claims before acting. A persona or reviewer confidently asserting "the button is broken / the screen 404s" is an opinion until you check it live yourself. Separate directional persona findings from objective bugs you reproduced.
• Preserve the fallbacks. Only revise the concepts the tests point at; leave the losing variants untouched so the next test still has a clean comparison baseline. This is the scope-creep gotcha, enforced across the whole loop.
• State the caveat. N LLM role-plays are directional, not proof. The strongest read is adversarial-persona convergence plus agreement with real funnel data; say so.

The rest of this skill describes the iterate node itself, which is what runs at each → iterate above.

Why traceability is the whole game

Design iteration fails in a specific way: someone reads a pile of critique, rewrites the mockups "better," and now nobody can say which fix answered which problem. Re-testing then can't attribute a win or a regression to anything. The fix is boring and reliable: triage every piece of feedback, decide what you're doing about it, and record the mapping. That record is the deliverable as much as the pixels are.

Inputs you accept (any subset)

• A design artifact: live URL (Surge/localhost), an HTML/JSX/component file, a Figma-style spec, or a set of image mockups.
• One or more feedback sources. They arrive in different shapes:
  • design-review → 13-question answers + Nielsen heuristic findings + before/after fixes.
  • marketing-psychology / persuasion review → framing / urgency / anchoring / risk-reversal critique of copy and offers.
  • another-perspective → a council synthesis (Skeptic, User Advocate, Pragmatist, etc.) about the decision, not the pixels.
  • synthetic-userstudies → per-persona "why I'd bounce here" reactions.
  • UI lint pass → file:line findings tied to named rules (motion, typography, spacing).
  • raw user notes → freeform, often terse.

If the artifact is a live URL or on-disk file, open and read it first. You cannot iterate on a design you haven't actually looked at.

The loop

1. Read the artifact and the feedback

Load the current design and every feedback source. If multiple sources disagree (a council says "too much friction," a user study says "not enough guidance"), name the tension explicitly rather than silently picking a side.

2. Triage into keep / change / kill

Go through every distinct feedback item and label it. Not all critique deserves a change: some is noise, some contradicts higher-priority signal, some is a taste difference you'll consciously reject.

• KEEP — the design already handles this; no change, note why so it doesn't get re-raised.
• CHANGE — a real problem with a clear fix. This is the bulk of the work.
• KILL — the concept has a flaw serious enough that the fix is "drop this variant," not "tweak it."

Prioritize CHANGE items by leverage: fix what blocks the most users or breaks the core value moment first, polish later. When two items conflict, the one backed by the stronger evidence (real user reaction > heuristic > taste) wins, and you record that you made that call.

3. Reach for a design system (if one exists)

Before inventing spacing, colors, type, or components, look for the project's existing design language so your revision looks native instead of bolted-on. Search in this order, stop at the first hit:

1. A design-system skill for this project (if one exists), or a visual-identity doc (your visual-identity doc if you have one, or VISUAL-IDENTITY.md, DESIGN.md, STYLEGUIDE.md at repo root).
2. Design tokens in the repo: grep -ri "tokens\|--color-\|theme\|tailwind.config" --include=*.{css,ts,js,json}.
3. The artifact's own existing styles: reuse the classes/variables already on the page.

If you find one, conform to it and say which one you used. If you find nothing, that's fine: iterate on the artifact's own internal consistency and note that no system was available. A missing design system is never a reason to stop.

4. Apply the revision

Produce the new version in the same medium as the input (edit the HTML/component, regenerate the image mockups, update the spec). Change only what the triage justifies. Resist the urge to redesign untouched areas: scope creep destroys the ability to attribute the next test's result.

5. Emit the change log

Alongside the revised artifact, output a compact table mapping each decision back to its source. This is what makes the next test meaningful:

## Iteration <N> change log

Design system: <name of system used, or "none found — iterated on internal consistency">

| Feedback (source) | Verdict | What changed |
|---|---|---|
| Carousel has no action, users bounce (synthetic-userstudies, persona 2) | CHANGE | Replaced slide 1 with a tappable ticker that returns a live verdict |
| Promo reads as a nag (marketing-psychology review) | CHANGE | Moved promo to post-value reward framing |
| Weekly plan splits attention (another-perspective, Skeptic) | KILL | Dropped the weekly-plan variant entirely |
| CTA contrast is fine | KEEP | Already meets contrast; no change |

Unresolved tensions: <any conflicting feedback you had to arbitrate, and how>
Open for next test: <what the next round should specifically measure>

6. Hand back for re-testing

You do not test your own output here (that circularity is how designs drift). Point the revised artifact at the next test in the pipeline (synthetic-userstudies, another design-review, a UI lint pass, etc.) and state what changed so the tester knows what to look for.

Where this sits in a design pipeline

A typical loop, with this skill as the recurring node:

design-mode + design-system  →  design-review + marketing-psychology review + another-perspective (parallel)
      →  DESIGN-ITERATION  →  synthetic-userstudies  →  DESIGN-ITERATION  →  UI-polish pass

design-iteration is deliberately the only step that mutates the artifact between tests. Keeping mutation in one named place is what preserves attribution across the whole loop.

What this skill is NOT

• Not a critique generator. It consumes feedback; it doesn't produce the review. Use design-review, a UI lint pass, synthetic-userstudies, etc. for that.
• Not from-scratch design. For exploring new layout paradigms use a UI-prototype-exploration workflow; for building a fresh interface use a dedicated frontend-design skill or your usual UI-building workflow.
• Not final polish. The last-mile motion/typography/spacing sweep belongs to a dedicated UI lint/polish pass. This skill makes the substantive revisions between tests; that pass makes the shipped version feel finished.

Gotchas

• Silent scope creep is the main failure. "Improve the mockups" tempts you to touch untouched areas. Every edit not traceable to a triaged feedback item destroys the next test's ability to attribute a win or regression, which is the entire point of this node. If you can't name the critique a change answers, don't make the change.
• Conflicting sources need arbitration, not averaging. When a council says "too much friction" and a user study says "not enough guidance," don't split the difference into mush. Name the tension, pick the side with stronger evidence (real user reaction > heuristic > taste), and record that you made the call in the change log's "Unresolved tensions" line.
• Don't test your own output. Iterating and then judging the same artifact yourself is how designs drift toward your taste instead of the evidence. Hand back to a test skill; that separation is deliberate.
• A missing design system is never a reason to stall. If the search in step 3 finds nothing, iterate on the artifact's own internal consistency and note it. Don't invent a system or block on one.

The one rule this whole skill protects: mutation happens only here, and every mutation is traceable to a critique. That is what lets the loop measure improvement instead of just noticing change.