# Design Iteration

> 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 exist…

- **Type:** Skill
- **Install:** `agentstack add skill-exiao-pm-skills-design-iteration`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [exiao](https://agentstack.voostack.com/s/exiao)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [exiao](https://github.com/exiao)
- **Source:** https://github.com/exiao/pm-skills/tree/main/design/design-iteration

## Install

```sh
agentstack add skill-exiao-pm-skills-design-iteration
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](#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 ``"*. 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](#3-reach-for-a-design-system-if-one-exists)) 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  change log

Design system: 

| 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: 
Open for next test: 
```

### 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.**

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [exiao](https://github.com/exiao)
- **Source:** [exiao/pm-skills](https://github.com/exiao/pm-skills)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-exiao-pm-skills-design-iteration
- Seller: https://agentstack.voostack.com/s/exiao
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.