/ui-refine-loop

name: ui-refine-loop
description: Unattended Impeccable check → fix loop on one page or component. It reads the target's code, grills Eric (at most 10 questions, "you pick" welcome) into a per-project taste and direction file, then runs bounded rounds. Each round a fresh checker runs Impeccable critique and audit (design review and detector in separate sub-agents) and ranks typed problems, and a fresh fixer chains the matching Impeccable commands (polish last), keeps checks green or reverts, and commits. Shots cover before vs now, light and dark, 1440 and 390, plus section crops. A fresh finish reviewer grades every fix, and the loop ends in a draft PR with a Before | After table. Standalone only: started by `/ui-refine-loop <route|component>`, never by the super-board lanes. Use when the user says "ui-refine-loop", "/ui-refine-loop", "refine loop", "iterate on this page", "polish this page with impeccable", or "keep polishing".
argument-hint: "<route | component path | description> [\"<what's wrong / what we want>\"] [--rounds N] [screenshot paths…]"

ui-refine-loop: Impeccable check → fix, bounded

Impeccable's `critique` and `audit` find problems once, and each fix command (`distill`, `layout`, `polish`, and the rest) fixes one kind once. This skill chains them into a short unattended loop. Each round, **fresh checkers** find and rank the problems, then a **fresh fixer** picks the right Impeccable commands and lands one green commit. A short ledger is the only thing carried between rounds, because a checker that watched the last edits grades the intent, not the pixels.

/ui-refine-loop /dashboard/reports "the summary strip feels cramped"
/ui-refine-loop src/components/ReceiptViewer.tsx "mobile layout breaks under 400px" --rounds 3
/ui-refine-loop "the billing page plan cards" "too loud, make it calmer" ~/Desktop/billing.png

Rounds default to **5**. Impeccable advises bounded passes; asking for more than 8 gets a one-line warning about cost and diminishing returns. In the paths below, `<main>` is this checkout, `<wt>` is the refine worktree, `<run>` is its run dir, and `<skill>` is this skill's folder.

It is **standalone**: only a person starts it, with `/ui-refine-loop <where>`. The super-board lanes never run it. It works on its own `refine/<slug>` branch from `HEAD` and ends with finish grades and a **draft PR** for human review. It never merges.

1. Read the target's code first

The prompt names where: a route, a component path or a description. Turn it into a **route** to screenshot and the **scope** paths the fixer may edit:

• **Route**: the page file that serves it (`app/**/page.*`, `pages/**`, `src/routes/**`, or whatever the framework uses), plus the component folders it imports.
• **Component path**: that file's folder. The route is a page that renders it (grep for its import), or its Storybook story.
• **Description**: search for it. Any screenshots the user pasted show which surface they mean.

Then **read that code area** before asking anything: the page, the components it renders, the shared UI it uses, the tokens and theme (including how dark mode works), and `PRODUCT.md` / `DESIGN.md` if they exist. Write a one-paragraph **context** for the sub-agents: what the surface does, its components, its tokens, its dark-mode mechanism. Use a sub-agent for this if it spans many files.

If two readings of the target are plausible, or target files are dirty in `<main>` (the worktree branches from `HEAD`, so uncommitted edits won't be in it), make that the grill's first question.

2. Grill (at most 10 questions)

Follow [`references/grill.md`](references/grill.md), which uses the `grilling` skill's pattern: numbered questions with your recommended answer under each, asked in waves. Wave 1 is 3 questions; later waves come only if needed, and the total is 10 at most. "You pick" accepts your recommendation. Don't ask what the code or an existing taste file already answers. Keep the answers for step 3.4.

3. Setup (once)

1. **Settings.** Run `bash <skill>/scripts/refine-setup.sh detect`. It resolves the dev command, checks, env files, auth script, data states, taste file and Impeccable install from the super-board config's `refine` block, then `package.json`, then defaults ([`references/config.md`](references/config.md)). If `devCommand` is null, ask once (and suggest saving it as `refine.dev_command`). 2. **Impeccable detection.** Detect's `impeccable` field is `{layout, skillDir, version, detect, context}` or null. It handles both installs: v4.4+ ships a launcher (`scripts/impeccable detect --json`, `scripts/impeccable context`), and v4.0.x ships Node scripts (`node scripts/detect.mjs --json`, `node scripts/context.mjs`). It searches `.claude/skills/impeccable` and `.agents/skills/impeccable` in this directory and every parent, then `~`. **If `warnings` is non-empty, show them to the user now, verbatim.** With no Impeccable, the loop runs on [`references/rubric.md`](references/rubric.md), the result carries `degraded`, and the PR says so. It is never silent. 3. **Worktree, deps, server.** `slug` is the route or file in kebab-case.

   bash <skill>/scripts/refine-setup.sh up --slug <slug>

This creates `<wt>` = `.claude/worktrees/refine-<slug>` on branch `refine/<slug>`, with `<run>` = `<wt>.run` beside it, so shots, auth state and logs never reach a commit. It records the base sha and base branch. It gives the worktree a node_modules: an APFS clone, else a reflink copy, else a frozen-lockfile install. It copies the env files, starts the dev server on a free port, and waits for `ready_path`. Exit 69 means the server never came up: read `<run>/dev.log`, fix it once, or tell the user. If the app can't run but the target has a story, set `refine.dev_command` to Storybook with `--port $PORT --ci --no-open`; the route becomes `/iframe.html?id=<story-id>&viewMode=story`. 4. **Taste and direction file.** Write the grill's answers to `<wt>/<tas