review-ui

review-ui · UI/UX acceptance review

Determine whether the implemented interface meets expectations, and provide a checklist: after another agent fixes everything on the list, the next round's score should improve noticeably. This skill, together with apply-ui-review forms an acceptance loop: each call evaluates one round, then re-evaluates after fixes, until it passes, stalls and is handed to the user for a decision, or the user explicitly lets it go.

Each round is scored by an independent reviewer with a fresh context against the goals. The main agent is only responsible for collecting, verifying, and adjudicating, and does not score its own fixes. The loop's state all lives in persisted files: the goal package, per-round screenshots, raw review conclusions, reports, and fix records. Whether called manually in alternation or advanced automatically with goal, it continues by the same rules.

Only real effects count. Scores, gaps, and judgments can only come from three kinds of evidence: screenshots taken this round of the product actually running, operations actually performed, and results actually measured on the page. Code, diffs, plans, design intent, and inferences like "based on the code it should behave this way" can only be used to find entry points and locate problems; they cannot be used to score, open gaps, close gaps, or determine pass. Units for which real effects cannot be obtained are not scored and are judged as requiring more evidence: better not to review at all than to imagine.

Default delivery: establish the goal package in the first round; each round's screenshots, raw review conclusions, and full report are persisted and read back. In chat, give the acceptance verdict first, then the score trajectory, key gaps, screenshot locations, and next command. Product code, plans, and historical reports are read-only; do not fix, commit, or advance progress.

references/ Resolved relative to this file. The target repository's startup method, accounts, design specifications, and screenshot tools are discovered at runtime. Language follows the user.

Applicable boundaries

Applies to acceptance where there is a runnable interface: optional UI acceptance after a plan is implemented and passes code review, re-review after fixes, and single acceptance when the user provides a page and a target image or specification.
Does not apply to: code defect review, use review-code; fixing gaps, use apply-ui-review; finding visual direction, use design-reference; interaction scheme selection, use ui-pattern-research; maintaining DESIGN.md, use design-md。
When real effects cannot be obtained (no usable rendering or screenshot tools, the app won't start, the state cannot be reached), judge as requiring more evidence per the rules above, explaining what is missing and how to supplement it.

Loop mode and capability detection

First determine this loop's prefix, check <前缀>.ui-review.json, existing reports, and installation receipts. When there is existing pure Markdown history but no managed index, continue the manual process; taking over requires an explicit import. When it is entirely new with no index, no old loop history, and the user has requested UI acceptance, first probe according to the protocol below; after the real engine matches the review verbs, you may review begin establish a managed loop; when the CLI is missing or capabilities do not match, use the manual process. Without the CLI it is still possible to read the original text, capture the real interface, and persist manually; without a machine index you must not claim to have taken over.

When there is an existing managed index, first follow Phoenix review protocol Verify the identity of the pinned engine version and the review protocol it actually supports. When it is missing, mismatched, a future schema, or the index is corrupted, only read history and may collect unregistered materials; do not score, adjudicate, write dispositions, counts, or report generation areas, and do not create a new loop to bypass the original state. Explain how to restore a matching engine, and after restoration continue with the original round and revision.

When matched, review begin allocates the round and freezes the target and matrix; afterward, register collection, read the whitelisted packet, register the review source text, adjudicate, and read back in sequence. JSON input is constructed according to the actual typed examples returned by review --help and review schema --json , without guessing fields; examples are not evidence, and identity, hash, and revision must come from real operations and materials. Old Markdown enters the managed loop only through an explicit review import ; attempts or refactoring counts with unclear history cannot be treated as zero.

1. Anchor the object and target package

Read the applicable repository rules. When a development plan is provided, read the plan's frontend and interaction, real-environment and UI verification, and milestone acceptance, then follow the "requirement source" to read the interface requirements and UAT in the PRD. Also read the project DESIGN.md or theme specification, as well as the design mockups linked from the plan or PRD. When only a URL or route plus target image is provided, handle it as a single acceptance.
According to the naming rules of the report contract , determine the prefix and round. For a manual loop, take the existing maximum round; for a managed loop, read the index, and for an unfinished round continue the original round/revision without incrementing it yourself. When a report for this loop already exists, this round is a re-review; the "previous round" for each unit is the most recent round that covered it and had a review conclusion; a round that covered it but had no review conclusion at all (such as all sealed for lack of evidence) does not count.
According to target package and collection , locate or establish the target package and compute the target fingerprint. If the fingerprint differs from the one recorded in the previous round's capture.md , it means the expectations or target image have changed, and this round is arebuilt baseline: the historical best score, stagnation determination, and refactoring records all restart from this round. Changing only the "collection" section does not affect the fingerprint.
After the target package is established, this skill does not rewrite the expectations in it; it may only modify the "collection" section and record it in the change log. When the target image and the specification contradict each other, list it as a pending adjudication item; when a unit has neither a target image nor a specification, that unit needs supplementary evidence. Other units are reviewed as usual.

2. Collect screenshots for this round

Start or connect to the environment under test according to the target package, record the version under test (HEAD, uncommitted change fingerprint, or build number) and the access address, and confirm that the current code is running rather than an old build. Run services started temporarily for the review in the background, note how to stop them, and stop them before finishing. Use only test accounts and seed data, and do not write to or perform destructive operations on real business data.
Each round collectsallcells of the target package (unit × state × viewport × theme), so that regressions can be found. When the user limits the scope, collect only that scope and mark the rest as "not re-reviewed this round". Re-shoot under the same conditions each round, without picking flattering angles or data.
Every screenshot must be actually taken on the real product in this round; the requirements are in the "authenticity" part of target package and collection . Images that do not meet the requirements, such as design mockups, old screenshots, or simulated pages written for the review, are all treated as not collected.
The interaction unit operates step by step; after each action, capture a keyframe, including the focus frame during keyboard walkthroughs. In the operation log, record only the actions actually performed and the results seen in the screenshots; do not write inferences such as "should" or "expected to." During collection, also save console logs and failed requests, and leave them for analysis after the review.
When a state cannot be reached, first look for the project's existing data generation, mock, or route interception methods. For cells that still cannot be collected, state the reason clearly; do not pass off a similar state as the real one.
Save the version under test, target fingerprint, collection conditions, the cell and source corresponding to each image, and the cells that were not collected, according to the report contract. For manual loops write capture.md; for managed loops use review capture add to register and read back the generated manifest; for supplementary collection, append an attempt, and do not overwrite the original images or old records.

3. Independent review

According to independent review dispatch and recheck:

For each round, dispatch a subagent with a completely fresh context as the reviewer, read-only, and it does not spawn further subagents. The reviewer receives only three things: the target package; this round's screenshots,capture.md , and interaction log; and each unit's screenshots and judge.mdfrom the previous round (containing only the scores and gaps the reviewer itself gave).
Things not given to the reviewer: code, diff, commit message, fix log, fixer's own account, full report, machine check results, and threshold score. And require the reviewer to open only the listed materials, so as not to be biased by "it has already been fixed" and not to pad scores toward the threshold.
For managed loops use review judge-pack 's whitelist materials for dispatch; do not follow links within the materials to open excluded files. The packet's hash binds this batch of materials; confirm that the reviewer uses the same batch of materials; the whitelist is an information boundary and does not pretend to be the host's file permission sandbox.
When there are many cells, dispatch in parallel grouped by unit. For new gaps, first use temporary IDs, and after the main agent merges them, assign unified IDs. For cells that cannot be seen in the review report, the main agent performs supplementary collection and then dispatches a completely fresh reviewer to re-review the affected units, taking the lower score.
If no subagent can be dispatched, or the reviewer cannot open the images:
- If the current conversation has not participated in the implementation or fixing of this interface: the main agent may review on its own. Before review, read only the target package, this round's and the previous round's screenshots,capture.md , and judge.md; first review and save judge.md, then do the things in Section 4; note "single-context review" in the report.
- If the current conversation has participated: do not score in this conversation; provide the command to run this skill in a new conversation.
The main agent does not change scores, delete gaps, change threshold items, or replace the reviewer for re-review due to disputes. If it believes the review is mistaken, only attach a verification note under that gap, hand it to the fixer for verification, and have the reviewer recheck in the next round.
When this round would be judged as passing, but the lowest unit score is strictly below "threshold + 0.5," dispatch another completely fresh reviewer with the same batch of materials to confirm; when it is exactly equal, it is not mandatory. For each unit, select the complete set of four-dimensional scores and reasons from the reviewer with the lower total score, and take the union of all reviewers' gaps; do not piece together dimension by dimension a score that does not exist.

4. Adjudication and persistence

Save each reviewer's original text and this round's merged judge.md; for managed loops, also use review judge add to register the original text and the faithful structured results and read them back. After that, do the following things:
- Do machine checks, all executed on the running page: analyze the logs saved during collection, measure overflow in the page, inject accessibility scans, and do keyboard walkthroughs with real key presses. Issues inferred from code or stylesheets do not count as check results; they can only indicate where to supplement captures or conduct actual measurements;
- Read the complete report from the previous round and the fix records from each round. The fix record is the one in the plan record directory that contains the "UI Acceptance Fix" section; when there is no plan, it is <前缀>.ui-review.applied.md；
- Determine the threshold: the one specified by the user this time takes priority; otherwise follow the one recorded in the previous round's report; if neither exists, default to 8/10.
Complete the adjudication according to the report contract:
- The main agent rechecks the previous round's machine check gaps and the gaps verified by the main agent;
- Calculate this round's score, threshold items, pending adjudication items, and stagnation status;
- Reach the acceptance verdict.
For the manual loop, write the report according to the report contract; for the managed loop, use review finalize Submit the adjudication with the current revision; do not handwrite the generated section. Return confirmation_required When this round is still a draft, complete the confirmation review before adjudicating; an operation exit of 0 by itself does not mean acceptance passed. After writing, read back the status, report, and links, and verify the verdict, score, and numbering mapping. If writing fails, truthfully state that it was not persisted, and deliver the verified content in chat.

5. Acceptance verdict and next steps

The final reply should first give a one-line acceptance verdict (see the report contract for the definition), then the score trajectory, the lowest-scoring unit and main gaps, and the latest screenshot location, and finally the next-step commands that can be copied directly. The commands should follow the current client's skill invocation syntax (e.g., Codex $apply-ui-review、Claude Code /apply-ui-review), with actual file paths filled in.

When the goal package has just been established in the first round, list the expected sources and assumptions and ask the user to confirm; after the user modifies the expectations, the next round is reviewed against the rebuilt baseline.

Acceptance verdict	Next steps
Needs modification	`apply-ui-review <本报告路径>`, and after fixing, use this skill to review again. When there is a "stagnation warning", explain whether it is a global refactor or which unit is being refactored. When there are "pending adjudication" items, list these items at the same time and ask the user to decide; the fixing party should first handle the remaining gaps
Acceptance passed / User exemption passed	Provide the latest screenshot and ask the user whether to continue polishing: if polishing is desired, `apply-ui-review <本报告路径>` handle the remaining gaps, then review again. If not polishing, and if this round's UI fixes changed code (commits registered as "UI Fix" or uncommitted changes), first `review-code <计划路径>` review these changes; afterward, the plan comes from the PRD's optional `review-prd-dev-gaps <计划路径>`
Needs user adjudication	List the stagnation or pending adjudication items, the approaches already tried, and a comparison between the goal and the current screenshot, and ask the user to choose from the following three options
Needs supplementary evidence	List the missing environment, accounts, data, tools, or goals, as well as how to obtain them; after they are completed, then `review-ui <计划路径或原范围>`. The gaps of already-evaluated units can first be `apply-ui-review <本报告路径>`

Three options when user adjudication is needed:

Accept the overall current state and record it as exemption passed;
Accept a certain deviation or modify expectations; after user confirmation, change the goal package, and rebuild the baseline in the next round;
Provide materials or direction, then execute apply-ui-review <本报告路径>。

When the user explicitly indicates acceptance of the current overall interface, append an exemption record according to the report contract and read it back. Exemptions must not be written as resolved.
Only provide suggested commands; do not start fixes, code reviews, or difference checks on your own.

Invocation example:

使用 $review-ui goal/LOGIN.md
使用 $review-ui goal/LOGIN.md，设计稿在 design/login/，门槛 8.5 分。
使用 $review-ui 验收 http://localhost:5173/orders，目标图 docs/design/orders.png。
使用 $review-ui goal/LOGIN.md，只复查 U2。

Project status write-back

If the repository already has a registered status ledger, or a repository root exists .xgent-ai/sdlc/protocol.md(compatible with the existing docs/project-status/protocol.md; when both coexist and no switch has been registered, verify first and do not dual-write). After delivering the original artifact, read the ledger's write-back rules (for the default directory, read the above protocol), update the current status and source links of the affected objects according to the in-repository protocol, and maintain the index when necessary; in v4, directly update the current page for routine cases, and for event retention conditions or legacy event requirements, the in-repository protocol prevails; when not enabled, do not automatically create tables and do not depend on separately installed skills. When read-only/chat-only/no-save and managed capability anomalies occur, the read-only boundary takes precedence; registration failures must be explained and do not affect the faithful delivery of the completed original artifact.

Each actual review round registers an independent review ID, stating the version under test, target fingerprint, scope, verdict, score, and report path; re-reviews are linked to the previous round. If the protocol's review_type has no UI type, register it as other, and note "UI acceptance review" in the summary. Passing acceptance must not be registered as merged, released, or passing final product acceptance.