Back to Details

ui-percept-rapid-feedback

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

UI Percept Rapid Feedback

UI Percept 快速反馈

Use this skill when you need quick iteration on Quick Maths screen quality, especially spacing, alignment, sizing consistency, truncation risk, and palette cohesion.
This skill avoids subjective pass/fail judgment and instead produces concrete, measurable feedback that an agent can use to patch SwiftUI code and rerun.
当你需要对Quick Maths的界面质量进行快速迭代时使用此技能，尤其适用于间距、对齐、尺寸一致性、截断风险和调色板统一性相关的优化场景。
该技能不会给出主观的通过/失败判定，而是生成具体、可量化的反馈，Agent可基于这些反馈修改SwiftUI代码后重新运行。

When To Use

适用场景

  • After UI changes in 
    quick-math-swift
  • When reviewing one or more captured screens (
    home
    , 
    game
    , 
    reward
    )
  • When you want a higher aesthetic bar than default ui-percept rules
  • When you need output saved to files for repeatable agent loops
  • 在
    quick-math-swift
    项目中完成UI修改后
  • 审查一个或多个已捕获的界面（
    home
    、
    game
    、
    reward
    ）时
  • 你需要比ui-percept默认规则更高的美学标准时
  • 你需要将输出保存到文件以支持可重复的Agent循环时

Prerequisites

前置条件

  • quick-math-swift
    repo is present and buildable
  • ui-percept
    repo exists at 
    /Users/vabole/repos/ui-percept
    or passed via 
    --ui-percept-dir
  • iOS simulator + 
    xcodebuild
    available for capture
  • 存在
    quick-math-swift
    代码库且可正常构建
  • ui-percept
    代码库存放在
    /Users/vabole/repos/ui-percept
    路径下，或通过
    --ui-percept-dir
    参数指定路径
  • 安装了iOS模拟器和
    xcodebuild
    以支持界面捕获

Workflow

工作流程

  1. Run the helper from quick-math root:
bash
bash .apple-skills/skills/ui-percept-rapid-feedback/scripts/run-feedback.sh --mode improve --screens game
  1. Read:
  • .ui-captures/ui-percept-skill/<run-name>/feedback-overview.json
    first
  • .ui-captures/ui-percept-skill/<run-name>/codex-jury-prompt.md
    for Codex vision review mode
  • .ui-captures/ui-percept-skill/<run-name>/codex-decision-log.md
    for narrated decision tracking
  • .ui-captures/ui-percept-skill/<run-name>/feedback-report.md
    second
  • .ui-captures/ui-percept-skill/<run-name>/feedback-report.json
    only when drilling down
  1. Prioritize fixes in this order:
  • blocker
    and 
    major
    lint issues
  • repeated 
    rule
    clusters in report summary
  • top 
    suggestions
    from 
    signals.json
  1. Patch SwiftUI code, then rerun the same command.
  1. 在quick-math项目根目录运行辅助脚本：
bash
bash .apple-skills/skills/ui-percept-rapid-feedback/scripts/run-feedback.sh --mode improve --screens game
  1. 按顺序读取以下文件：
  • 首先查看
    .ui-captures/ui-percept-skill/<run-name>/feedback-overview.json
  • Codex视觉审查模式下查看
    .ui-captures/ui-percept-skill/<run-name>/codex-jury-prompt.md
  • 查看
    .ui-captures/ui-percept-skill/<run-name>/codex-decision-log.md
    获取带说明的决策追踪记录
  • 其次查看
    .ui-captures/ui-percept-skill/<run-name>/feedback-report.md
  • 仅在需要深入排查时查看
    .ui-captures/ui-percept-skill/<run-name>/feedback-report.json
  1. 按以下优先级安排修复：
  • blocker
    和
    major
    级别的代码检查问题
  • 报告摘要中重复出现的
    rule
    集群
  • signals.json
    中的优先级最高的
    suggestions
  1. 修改SwiftUI代码，然后重新运行相同的命令。

Commands

可用命令

Run selected screens:
bash
bash .apple-skills/skills/ui-percept-rapid-feedback/scripts/run-feedback.sh --mode improve --screens home,game,reward
Switch to build-oriented prompt mode:
bash
bash .apple-skills/skills/ui-percept-rapid-feedback/scripts/run-feedback.sh --mode build --screens game
Archive before/after screenshots with commit-hash labels:
bash
undefined
运行指定界面的检查：
bash
bash .apple-skills/skills/ui-percept-rapid-feedback/scripts/run-feedback.sh --mode improve --screens home,game,reward
切换到面向构建的提示模式：
bash
bash .apple-skills/skills/ui-percept-rapid-feedback/scripts/run-feedback.sh --mode build --screens game
用提交哈希值作为标签存档修改前后的截图：
bash
undefined

before changes (uses current HEAD hash by default)

修改前（默认使用当前HEAD的哈希值）

bash .apple-skills/skills/ui-percept-rapid-feedback/scripts/run-feedback.sh
--mode improve --screens game --archive-stage before --archive-user "$USER"
bash .apple-skills/skills/ui-percept-rapid-feedback/scripts/run-feedback.sh
--mode improve --screens game --archive-stage before --archive-user "$USER"

after changes (pass the new commit hash explicitly)

修改后（显式传入新的提交哈希值）

bash .apple-skills/skills/ui-percept-rapid-feedback/scripts/run-feedback.sh
--mode improve --screens game --archive-stage after --archive-user "$USER" --git-hash <new_commit_hash>

Low-friction helper (auto hash + optional history commit):

```bash
bash .apple-skills/skills/ui-percept-rapid-feedback/scripts/run-feedback.sh
--mode improve --screens game --archive-stage after --archive-user "$USER" --git-hash <new_commit_hash>

低门槛辅助脚本（自动生成哈希+可选历史提交）：

```bash

before phase

修改前阶段

bash .apple-skills/skills/ui-percept-rapid-feedback/scripts/archive-round.sh --phase before --screens game
bash .apple-skills/skills/ui-percept-rapid-feedback/scripts/archive-round.sh --phase before --screens game

after phase

修改后阶段

bash .apple-skills/skills/ui-percept-rapid-feedback/scripts/archive-round.sh --phase after --screens game

Skip automatic history commit if you only want artifacts:

```bash
bash .apple-skills/skills/ui-percept-rapid-feedback/scripts/archive-round.sh \
  --phase after --screens game --no-history-commit
Use existing captures without rerunning XCUITest:
bash
bash .apple-skills/skills/ui-percept-rapid-feedback/scripts/run-feedback.sh --screens game --skip-capture
Set custom ui-percept path:
bash
bash .apple-skills/skills/ui-percept-rapid-feedback/scripts/run-feedback.sh \
  --screens game \
  --ui-percept-dir /path/to/ui-percept
Analyze a specific archived artifact directly (no new capture):
bash
bash .apple-skills/skills/ui-percept-rapid-feedback/scripts/run-feedback.sh \
  --tree .ui-captures/game/ui_tree.json \
  --screenshot .ui-captures/ui-percept-v2/game-fast/full.png \
  --screen-name game-fast \
  --run-name game-fast-review
bash .apple-skills/skills/ui-percept-rapid-feedback/scripts/archive-round.sh --phase after --screens game

如果你只需要产物，可跳过自动历史提交：

```bash
bash .apple-skills/skills/ui-percept-rapid-feedback/scripts/archive-round.sh \
  --phase after --screens game --no-history-commit
使用已有的捕获结果，无需重新运行XCUITest：
bash
bash .apple-skills/skills/ui-percept-rapid-feedback/scripts/run-feedback.sh --screens game --skip-capture
设置自定义ui-percept路径：
bash
bash .apple-skills/skills/ui-percept-rapid-feedback/scripts/run-feedback.sh \
  --screens game \
  --ui-percept-dir /path/to/ui-percept
直接分析指定的已存档产物（无需新的捕获操作）：
bash
bash .apple-skills/skills/ui-percept-rapid-feedback/scripts/run-feedback.sh \
  --tree .ui-captures/game/ui_tree.json \
  --screenshot .ui-captures/ui-percept-v2/game-fast/full.png \
  --screen-name game-fast \
  --run-name game-fast-review

Notes

注意事项

  • This skill uses 
    references/high-bar-rules.yaml
    to raise visual standards.
  • Keep feedback evidence-based: element IDs, measured values, and repeatable signals.
  • Context hygiene rule: load 
    feedback-overview.json
    first and only open per-screen drilldown files for the issue you are fixing.
  • For opinionated UX/aesthetic review, apply 
    references/jury-review-mode.md
    .
  • For round-by-round history and commit discipline, apply 
    references/round-commit-workflow.md
    .
  • 该技能使用
    references/high-bar-rules.yaml
    配置来提高视觉标准。
  • 反馈均基于实证：元素ID、测量值和可复现的信号。
  • 上下文清晰原则：首先加载
    feedback-overview.json
    ，仅在处理对应问题时打开对应界面的深度排查文件。
  • 如需主观的UX/美学审查，可参考
    references/jury-review-mode.md
    。
  • 如需逐轮历史记录和提交规范，可参考
    references/round-commit-workflow.md
    。