apply-ui-review

apply-ui-review · Implement UI acceptance review

Turn the gap list given by an independent review into real interface improvements, so that the next round of review scores improves noticeably. The review has seen the goals and screenshots, so by default all fixable gaps are handled; however, each item must still be verified against screenshots, the goal package, and the specification, and anything the review got wrong or that contradicts the goal package must not be changed accordingly. When the user invokes this skill, they authorize verification, fixes, running necessary checks, submitting as agreed in the plan, and writing back records.

Both verification and self-check are based on the real interface in operation. Whether judging that the review got something wrong, that a gap no longer exists, or confirming that a fix is effective, the basis can only be screenshots actually taken in this round, styles and dimensions measured in the page, and the results of actual operations. You cannot draw conclusions just from reading code.

This skill does not score itself. Whether the fix is adequate is determined by the next round of review-ui independent review, so the disposition in the record can at most state "modified, pending review." Do not modify the review report, review screenshots, and judge.md; only after the user explicitly confirms should the user's decision be written into the goal package. Pushing, deployment, etc. are handled according to existing authorization.

references/ Resolved relative to this file. Startup method, component library, design specification, and check commands are discovered from the target repository. Language follows the user.

Loop mode and capability detection

First verify the <前缀>.ui-review.json and installation receipt corresponding to the report prefix. When there is existing pure Markdown history but no managed index, execute according to the manual process in this document; it must be explicitly imported to take over; the absence of the Phoenix CLI does not prevent reading reports, goals, and source materials, nor does it allow manual disposition to be claimed as managed status.

When a Phoenix managed index already exists, before fixing, verify the fixed-version engine identity and the actual review protocol; if it is missing, mismatched, a future schema, or corrupted state, only read history, may collect unregistered materials, and do not modify product code, goals, disposition, counts, report generation areas, or plan records. Explain how to restore a matching engine, and after restoration continue with the original loop; do not bypass it with manual downgrade, a new prefix, or resetting the baseline.

When the installation package includes review-ui , follow its Phoenix review protocol to discover capabilities and continuation status; when using this skill alone, still observe the above boundaries, and machine input relies only on the actual review --help and the typed examples returned by review schema --json , without guessing fields; examples are not evidence, and identity, hash, and revision are taken from real operations and materials. For managed disposition, use review apply record to register the current round, with the current applied revision; the import of old Markdown must be explicitly review import, and attempts with unclear history and refactor counts are not treated as zero.

1. Anchor input

1. Locate the UI acceptance report given by the user, find the plan, goal package, screenshot directory, and previous round report from the "review object" in the report header, and verify that they indeed correspond. When the user does not provide a report, the manual loop takes the .ui-review report with the largest round number from the context or the same directory as the plan; the managed loop reads the current report for this loop from the index, not by file modification time or guessed round number. If there are multiple reports and they cannot be distinguished, ask.
2. Handle according to the report's acceptance determination:
   • Needs modification：Handle fixable gaps. When there is a "stall warning", perform a refactoring round as described below. When there is "pending adjudication", do not change those items for now; record them as "pending decision", unless the user has already given direction on them this time.
   • Needs supporting evidence：The missing evidence is to be supplied by review-ui . For fixable gaps in units already evaluated in the report, they may be fixed first if the user requests it.
   • Needs user adjudication：When the user has not given direction this time, relay the options in the report and ask the user to decide, without touching the stalled and pending-adjudication parts; if direction has been given, follow it and record the user's exact words.
   • Passed acceptance / user-waived pass：Only when the user wants to continue polishing should the remaining gaps be handled.
3. When the user accepts a deviation somewhere or modifies expectations, after explicit confirmation by the user, write it into the comparison criteria or specification points of the corresponding unit in the target package, note the date and the user's exact words, and append a change record; the next review round will rebuild the baseline accordingly. When the user accepts the overall interface, prompt that it be recorded by review-ui as a waived pass; this skill does not modify the report.
4. Read the target package, the gap list in the report, pending-adjudication items and the previous review round table, as well as the fix records of previous rounds (see the record contract). Note the current HEAD and uncommitted changes, and distinguish which are the user's existing modifications and which are this round's fixes. When the user has limited it to gap numbers or units, handle only those.

2. Verification and prioritization

• Verify：Open the screenshots and target images referenced in the report one by one, and reproduce them in the running interface under the same unit, state, viewport and theme; then compare against the specification points, comparison criteria and DESIGN.md of the target package.
• Those that hold up：Proceed to fix.
• Not adopted：For the following situations, record "not adopted" and state the basis, without changing code: the review was mistaken (the running interface does not match the review description; attach a screenshot or measured value); it contradicts the target package or specification; it is a difference excluded by the comparison criteria. For gaps for which the report includes a verification note, verify them yourself as well, and if they indeed do not hold up, record them as not adopted.
• Pending decision or blocked：If fixing requires assets, copy, data, an interface or a product decision, record "pending decision" or "blocked", then continue handling other items.
• Pending verification：First confirm the current state in the running interface; if it is already fine, attach a screenshot and record it truthfully, and do not change code for it.
• Suggestion：No points deducted. If it is consistent with the specification and low-cost, it may be done along the way, but this must not reduce fidelity to the target.
• Order：Fix P0/P1 first; within the same severity, order by recoverable points from high to low. Prioritize common root causes that can eliminate multiple gaps at once, such as fonts not loaded, wrong token used, wrong layout primitive chosen, container constraints.

3. Fix

• Fix the root cause at the correct level; the levels from high to low are: theme and tokens, shared components, page layout, single-location styles. Use the tokens and existing components from DESIGN.md; do not write magic numbers to match screenshots, and do not duplicate a shared component for a single page. When the target indeed requires deviating from the specification, record the basis.
• Only change the code, styles, assets and tests necessary within the interface scope. If the fix requires changing interfaces, data contracts or planned scope, record "pending decision" and do not expand on your own.
• Preserve the user's existing modifications; do not reset, stash or revert.
• Regression: For gaps reported as regressions, first use the diff since the previous round to find which change introduced it, and fix that; do not trade it for another regression.
• Refactoring round: Do this when the report has a stagnation warning, and only for the warned scope (global, or the unit containing a certain gap). Stop fine-tuning:
  1. Write clearly why previous attempts did not work.
  2. List possible structural causes: wrong layout model or component; insufficient material quality; token or theme mismatch; fonts or images not loading correctly; container and breakpoint constraints; data shape; collection environment inconsistent with the target.
  3. Choose the one with the strongest evidence, and make one major structural change whose goal is a clear score improvement, not minor tweaks.
  4. Write the scope, assumptions, changes, and expectations into the record. Each scope has only one refactoring opportunity within the same baseline; the next round's review relies on this record to judge whether stagnation has been escaped.
• Record only what was actually changed: For gaps that cannot be finished in one round, mark them truthfully as "not handled"; they do not count as attempted. Only what was actually changed is recorded as "modified, pending review", and the next round's stubborn-gap determination is based on this.

4. Self-check

1. Start the current code, collect the affected units under the target package's conditions, and compare them yourself against the target; then quickly go through the other units to confirm no regressions were introduced. Self-check screenshots go in a temporary directory by default; when they need to serve as record evidence, save them to <前缀>.ui-captures/r<n>-apply/, without overwriting review screenshots.
2. Run the relevant checks required by the plan and the repository: component tests, unit tests, type checks, lint, build. When the project has visual regression tests, update snapshots only when the changes match the target, and state which ones were updated. When checks fail, distinguish whether it is a newly introduced regression, a pre-existing failure, or an environment issue; newly introduced regressions must continue to be fixed.
3. When the app cannot start or screenshots cannot be taken, record the self-check as "not run" and state the reason; do not judge it as fixed based on the code alone. The disposition is still modified, pending review, and the next round's review will determine it on the real interface.
4. Self-check does not count as acceptance: do not estimate a score, and do not claim the target has been met.

5. Submission, recording, and delivery

1. According to record contract save this round's disposition. For a manual loop, update the existing subsection for this round, do not append it again; for a managed loop, use review apply record and the current applied revision to update, and let only the engine project the blocks belonging to this loop and this round in the original record positions. When there is a conflict or the generated area has been manually edited, keep the original text and stop overwriting; use an explicit import to restore the generated area according to authoritative facts, then re-register the dispositions to be kept with the current applied revision, without automatically force-writing.

2. When the plan has a submission convention, or the user authorizes submission:

   • Stage only this fix and the record, follow the repository's commit conventions, and do not skip commit hooks;
   • After submitting, append to the "Commit" column of the milestone row corresponding to the completion record UI修复 plus the short SHA, then submit this registration separately.

   When neither is present, do not submit; leave the fix in the working tree, and the next round's review uses the working tree as the version under test. If submission fails, record it truthfully and do not fabricate a SHA.

3. Read back the changes to the record and plan; check the final diff to confirm there are no unrelated modifications, and that the review report, screenshots, and judge.md were not modified, and that the target package only gained decisions confirmed by the user, without overwriting the user's modifications.

4. Reply content:

   • Quantity of each type of disposition and key changes;
   • Refactoring assumptions (if any);
   • Self-check and inspection results;
   • Commit SHA, or the reason for not committing;
   • Record link;
   • Items pending user decision.

   At the end, give the next step: use review-ui <计划路径> for review, provided in the current client's wording (e.g., Codex $review-ui、Claude Code /review-ui). Do not start the review on your own.

Invocation example:

使用 $apply-ui-review goal/LOGIN.ui-review.r2.md
使用 $apply-ui-review goal/LOGIN.ui-review.r3.md，只处理 UI-04 和 UI-07。
使用 $apply-ui-review goal/LOGIN.ui-review.r5.md，U3 按设计稿改成两栏卡片。

Project status write-back

If the repository has a registered status ledger, or a repository-root .xgent-ai/sdlc/protocol.mdexists (compatible with the existing docs/project-status/protocol.md; if both exist and no switch is registered, verify first and do not write to both), after delivering the original artifact, read the ledger's write-back rules (for the default directory, read the above protocol), add this factual record in its format, and refresh the affected status pages and necessary indexes; if not enabled, do not automatically create a table and do not depend on separately installed skills. The read-only boundary takes precedence in read-only/chat-only/no-save cases and when managed capabilities are abnormal; registration failures must be explained and do not affect the faithful delivery of the completed original artifact.

Then register the disposition for the original review object: gap number, disposition, fixed version, self-check results, and unfinished items, and link the implementation record. "Modified, pending review" is not registered as resolved, and a fix cannot be registered as an independent review pass.