impeccable 的 /impeccable critique 全流程实战：双 Agent 设计评审、Nielsen 启发式评分与快照持久化

/impeccable critique 是 impeccable 设计语言体系中的"评审型"命令，用于对一个确定的页面、组件或文件执行双路独立评估（LLM 设计评审 + 确定性检测器证据），综合产出可量化的设计健康评分、按 P0–P3 分级的问题清单与 Persona 化测试结论，并将结果持久化为可追溯、可被后续命令（如 /impeccable polish）继承的快照。本文以 .pi/skills/impeccable/reference/critique.md 为骨架（仓库中 skill/reference/critique.md、plugin/skills/impeccable/reference/critique.md 等为同源副本），结合 critique_storage.rs 与 target_slug.rs 的底层实现，完整还原该命令的调用链、评分标准与持久化机制，读完即可在真实项目中独立跑通一次完整的设计评审闭环。

一、命令定位：一次 critique 运行到底产出什么

critique 命令的元信息定义在 skill/scripts/command-metadata.json 中：

Evaluate design from a UX perspective, assessing visual hierarchy, information architecture, emotional resonance, cognitive load, and overall quality with quantitative scoring, persona-based testing, automated anti-pattern detection, and actionable feedback.

一次成功的 critique 运行由四件事组成，缺一不可：

1. 解析一个稳定目标（[target]：特性、页面或组件），优先解析为源码路径而非 dev-server URL；
2. 并行运行两次相互隔离的独立评估：Assessment A（LLM 设计评审）与 Assessment B（检测器 + 浏览器证据）；
3. 综合成一份结构化设计评审报告，以聊天回复为主交付物；
4. 持久化一份快照存档，并向用户提出"接下来改进什么"的定向追问。

文档开篇的 Purpose 用一句话概括了这一点：Resolve one stable target, run two independent assessments, synthesize a design critique, persist a snapshot, and ask the user what to improve next. 聊天回复是主交付物，快照只是该次运行的归档。

二、硬性不变量（Hard Invariants）：失败模式即合同

critique 之所以可靠，在于它把"最容易失败的地方"写成了硬性规则。执行前必须逐条理解，任何一条被违反都意味着一次失败运行：

• 双评估缺一不可：Assessment A（设计评审）与 Assessment B（检测器/浏览器证据）都必须执行；
• 强制子 Agent 隔离：只要会话暴露了 sub-agent/Task 工具，A 与 B 就必须作为两个相互隔离的子 Agent 运行，绝不能内联执行。内联仅在"完全没有子 Agent 工具"（或宿主明确询问且用户拒绝）时允许，且属于降级运行；
• 降级必须亮横幅：任何降级原因下，报告第一行必须是 ⚠️ DEGRADED: single-context (<reason>) 横幅。静默降级的 critique 是失败 critique；
• 顺序约束：Assessment A 必须在检测器证据进入父上下文综合之前完成——检测器输出虽然是确定性的，但它会锚定判断，先看证据会污染设计评审的独立判断；
• 跳过检测器 = 失败：除非 impeccable detect 本身缺失或真实尝试后崩溃；
• 可查看目标必须浏览器检查（在浏览器自动化可用时）；
• 临时服务器纪律：仅为 critique 可视化启动的本地服务器必须后台运行、记录停止方式，并在最终报告前停止（除非用户要求保留）；
• 不得虚报 overlay：只有脚本注入成功且检测器确实在页面中运行后，才能声称存在用户可见的 overlay；
• 问题是响应的最后一项：先完整写完报告，再提问，问题之后不再有任何内容——因为结构化问题之后输出的散文会被挂起直到用户回答，写在问题后面的报告看起来就像从未运行过 critique；
• 必须有收尾：一次运行结束时，要么带定向追问，要么带一行字面 Questions skipped: <reason>，否则视为未完成。报告不是终点，收尾才是。

三、Setup：目标解析与 slug 确认

3.1 解析目标（Resolve the target）

把用户口头描述解析成具体文件路径或 URL，优先源码路径而非 dev-server URL——端口会漂移，路径不会：

用户说法	解析结果
"the homepage"	site/pages/index.astro 或 index.html
"the settings modal"	主要组件文件
"this page"	当前 URL 或源码文件

3.2 slug 确认：永不手写 slug

解析出目标后，先确认它能"干净地"生成稳定 slug：

.pi/skills/impeccable/scripts/impeccable critique-storage slug "<resolved-path-or-url>"

• 后续所有命令也都接受解析后的目标直接作为参数，并在内部推导相同的 slug，绝不要手写 slug；
• 该命令退出码非零时，跳过本次的持久化与趋势，但 critique 主体继续执行；
• 若存在 .impeccable/critique/ignore.md，先读取它，匹配到的 finding 静默丢弃——这是 critique 消费的唯一"前次运行输入"。

从源码看，slug 的生成逻辑位于 crates/context/src/target_slug.rs：目标会被归一化为 kebab-case（路径分隔符 /、\、. 折叠为 -，非字母数字字符同样折叠），超长目标采用"尾部保留 + SHA-256 哈希后缀"策略——SLUG_MAX 为 50，哈希取 8 位十六进制（见 target_slug.rs），保证不同长目标不会被截断成相同 slug；同时保留了 legacy_slug_from_target 兼容旧版本"纯截断 50 字符"的命名，供历史快照回读。URL 目标则解析 hostname + pathname 后参与 slug 化。

四、评估编排（Assessment Orchestration）：A/B 双轨隔离

• Assessment A 与 B 委托给两个独立子 Agent，彼此看不到对方输出，综合前不得向用户展示任何 findings；
• 子 Agent 门控：除非某宿主有特殊覆盖规则，只要暴露了 sub-agent/Task 工具就默认必须并行派发 A 与 B。"Unavailable" 只意味着"本会话没有暴露子 Agent/Task 工具"（或宿主询问且用户拒绝），不意味着"不方便"；
• 仅在子 Agent 确实不可用时才顺序降级：先完成并记录 A，再跑 B，然后综合，并必须输出降级横幅；
• 无论走哪条路，都必须在报告头声明（见"报告头 provenance"）。不亮横幅就跳过子 Agent 是 critique 命令最常见的失败方式；
• 浏览器自动化可用时，每个评估各自开一个新标签页，绝不复用已有标签页，即使它已经停在正确的 URL 上。

五、Assessment A：设计评审（Design Review）

Assessment A 阅读相关源码文件，并在浏览器自动化可用时目视检查真实页面，以设计总监的视角思考。评估维度：

• 设计特异性（Design specificity）：构图、交互与视觉语言是否扎根于本产品？换成无关产品能否原样使用？——这条必须在看到检测器输出之前作出判断；
• 整体设计（Holistic design）：层级、信息架构、情感契合、可发现性、构图、排版、色彩、可访问性、状态、文案与边界情况；
• 认知负荷（Cognitive load）：对照文末"认知负荷评估"一节，报告清单失败项与"可见选项 > 4 个"的决策点；
• 情感旅程（Emotional journey）：峰终定律（peak-end rule）、情感低谷、高利害时刻的安抚；
• Nielsen 启发式：对照"启发式评分指南"，对全部 10 条以 0–4 打分，允许按"模式适用性规则"对不适用条目标 n/a 而非强行给分。

返回内容：设计特异性结论、启发式分数、认知负荷、情感旅程、2–3 个优势、3–5 个优先问题、Persona 红旗、次要观察、挑衅性问题。

六、Assessment B：检测器 + 浏览器证据（Detector + Browser Evidence）

Assessment B 运行内置检测器与浏览器可视化证据，同样必须与 A 保持隔离直至两者都完成。

6.1 CLI 扫描

.pi/skills/impeccable/scripts/impeccable detect --json [target]

• 只传 markup 文件/目录作为 [target]，不要传纯 CSS 文件；
• URL 目标跳过 CLI 扫描，直接走浏览器可视化；
• 超大目录树（500+ 可扫描文件）应缩小范围或询问用户；
• 退出码语义：0 = 干净，2 = 有 findings；
• 检测器入口缺失或加载失败时，报告"确定性扫描不可用"并继续浏览器/人工评审。

6.2 浏览器可视化（Overlay 流程）

可查看目标在浏览器自动化可用时必须做浏览器可视化。本地文件用 localhost dev/static URL，除非浏览器明确支持否则避免 file://：

1. 新建标签页并导航；优先使用宿主原生/浏览器画布截图路径，不要手写 Playwright/Puppeteer 脚本；
2. 预检可变注入：通过设置 document.title 并追加一个 <script> 标签来验证；只读的 evaluate API 不算数；
3. 若不可变注入，跳过 live server、浏览器展示与注入，并报告回退信号；
4. 若可注入，依次执行：后台启动 .pi/skills/impeccable/scripts/impeccable live-server --background →（若支持）展示浏览器并标记 [Human] → 滚动到顶部 → 注入 http://localhost:PORT/detect.js → 等待 2–3 秒 → 读取 impeccable 控制台消息 → 停止 live server；
5. 多视图目标在 3–5 个代表性页面分别注入。

返回内容：CLI findings 的 JSON/计数、浏览器控制台 findings（如有）、误报清单，以及被跳过/失败浏览器步骤的具体原因。

B 返回可用 CLI findings 后，父上下文直接复用，除非 B 失败、被截断或遗漏了 count、规则名、文件位置，否则不重跑 impeccable detect。

七、综合评审报告（Generate Combined Critique Report）

综合不是简单拼接：要把两次评估编织在一起，指出 LLM 评审与检测器的一致之处、检测器抓到而 LLM 遗漏的问题、以及哪些检测器 finding 是误报。报告须在聊天中呈现完整结构化内容，不得用摘要 + 链接替代；快照只是该次运行的归档。

7.1 报告头 provenance（第一行必须声明）

• 双 Agent：Method: dual-agent (A: <agent-id> · B: <agent-id>)
• 降级：⚠️ DEGRADED: single-context (<reason, e.g. no sub-agent tool exposed>)

7.2 Design Health Score：Nielsen 十启发式评分表

#	Heuristic	Score	Key Issue
1	Visibility of System Status	?	[具体 finding 或 "n/a"]
2	Match System / Real World	?
3	User Control and Freedom	?
4	Consistency and Standards	?
5	Error Prevention	?
6	Recognition Rather Than Recall	?
7	Flexibility and Efficiency	?
8	Aesthetic and Minimalist Design	?
9	Error Recovery	?
10	Help and Documentation	?
Total		??/[applicable max]	[Rating band]

评分纪律：

• 适用最大值 = 实际打分的启发式数量 × 4：全部 10 条适用时为 /40，两条为 n/a 时为 /32。绝不能在部分条目缺失时打印 /40；
• 打分要诚实：4 分意味着真正出色，大多数真实界面的总分落在 20–32/40；
• 模式适用性：在 Persuade 与 Experience 型界面（落地页、campaign、作品集、作品集主体）上，启发式 7（灵活高效）与 10（帮助文档）可以标 n/a，其他确实无法适用于当前界面的启发式同理。n/a 需在 Score 单元格写一行理由，并按适用最大值重新归一化（如两条 n/a 时写 24/32），保证评级区间成比例。持久化快照必须记录适用最大值与哪些启发式被标为 n/a。

7.3 Design Specificity Verdict（从这一节开始）

• LLM 评估：对设计特异性的未锚定判断，覆盖整体一致性、结构同质化、品类可互换的选择、错过的产品个性机会；
• 确定性扫描：总结自动化检测器发现，附计数与文件位置，注明检测器抓到而自己遗漏的问题，并标记误报；
• 视觉 overlay（注入成功时）：告知用户在浏览器 [Human] 标签页中现在可以看到高亮问题的 overlay，并总结控制台输出；若尝试注入但失败，说明没有可靠的用户可见 overlay，并报告回退信号。

7.4 Overall Impression / What's Working / Priority Issues

• Overall Impression：简短的直觉反应——哪里有效、哪里无效、最大的机会点；
• What's Working：2–3 件做得好且能说出具体原因的事；
• Priority Issues：按重要性排序的 3–5 个影响最大的问题，每个标注 P0–P3 严重度，并给出四条结构化信息：
  • [P?] What：清楚命名问题；
  • Why it matters：对用户或目标的伤害；
  • Fix：具体修法（禁"考虑探索一下……"）；
  • Suggested command：可调用的命令（见下）。

允许建议的命令白名单（来自 command-metadata.json）：/impeccable adapt、animate、audit、bolder、clarify、colorize、critique、delight、distill、document、harden、layout、onboard、optimize、overdrive、polish、quieter、shape、typeset。

7.5 Persona Red Flags

从文末 Persona 参考的选择表中自动挑 2–3 个与当前界面类型最相关的角色；若 AGENTS.md 含 impeccable init 生成的 ## Design Context 节，再基于受众/品牌信息派生 1–2 个项目特定 Persona。对每个选中的 Persona，走一遍主要用户动作并列出具体红旗，例如：

Alex (Power User): No keyboard shortcuts detected. Form requires 8 clicks for primary action. Forced modal onboarding. High abandonment risk.

Jordan (First-Timer): Icon-only nav in sidebar. Technical jargon in error messages ("404 Not Found"). No visible help. Will abandon at step 2.

要点：写出具体元素与交互如何让每个 Persona 失败，不写泛泛的角色描述。

7.6 Minor Observations 与 Questions to Consider

• 次要观察：值得处理但优先级低的小问题快照；
• 挑衅性问题：可能解锁更好方案的提问，如"What if the primary action were more prominent?"、"Does this need to feel this complex?"、"What would a confident version of this look like?"。

写作纪律（Remember）：直接，模糊反馈浪费所有人的时间；具体——说"提交按钮"而不是"某些元素"；说出错在哪且为什么影响用户；给具体建议，砍掉"consider exploring..."；无情地排优先级——如果一切都重要，就什么都不重要；不要软化批评。

八、交付报告（Deliver the Report）：先交付，再记账

在进入任何持久化工作之前，先把完整报告写进聊天响应。这是交付物，其下都是记账。之所以这样规定，是因为最常见的失败方式恰恰相反：报告被一次性写进持久化 heredoc，运行结束时留下一个"完美的归档，但没人读过"。如果报告只存在于 .impeccable/critique/ 里，这次运行就什么都没产出。 持久化不是运行终点，之后还要输出趋势行并收尾。

九、持久化快照（Persist the Snapshot）

报告定稿后写入 .impeccable/critique/，方便用户回溯，也让 /impeccable polish 无需复制粘贴即可继承优先问题。Setup 阶段 slug 为 null（模糊或根级目标）时跳过本步骤。

9.1 步骤拆解

1. 正文写入临时文件（包含完整报告：启发式表、设计特异性结论、优先问题、Persona 红旗、次要观察、问题），但止于后面的"Ask the User / Recommended Actions"之前。注意：这是对已交付报告的副本，不是首次撰写；若你发现自己在 heredoc 里第一次撰写报告，说明跳过了"交付报告"，回去补上；
2. 通过环境变量传结构化元数据并写入：

IMPECCABLE_CRITIQUE_META='{"target":"<user phrasing>","total_score":<n>,"max_score":<n>,"na_heuristics":"<comma-separated numbers, or empty>","p0_count":<n>,"p1_count":<n>}' \
  .pi/skills/impeccable/scripts/impeccable critique-storage write "<resolved target>" <body-file>

3. 删除临时 body 文件（无论写入成功与否）。删除失败则简要提及 temp-file cleanup failed: <reason>，但不得阻塞 critique；
4. 读取趋势：.pi/skills/impeccable/scripts/impeccable critique-storage trend "<resolved target>" 5，返回最近 5 条 frontmatter 条目的 JSON 数组（含刚写入的这条）；
5. 向用户可见输出追加一行（在报告之后、提问之前）：

Trend for <slug> (last 5 runs): 24 → 28 → 32 → 29 → 32 (out of 40) Wrote .impeccable/critique/<filename>.

6. 收尾运行：转至"Ask the User"发问，或输出 Questions skipped: <reason>。不这样做运行就不完整——持久化是记账、清理不是结局，停在这里等于给用户一份没有前进路径的报告，也留给 polish 没有可继承的优先级。

这是 fire-and-forget 操作：不向用户展示 helper 的 JSON 输出，只展示人类可读的趋势行与写入路径。失败不阻塞主流程，打印错误继续。

9.2 底层实现：critique-storage 的五个子命令

critique_storage.rs 实现了完整的 critique-storage 命令，与文档流程一一对应：

• slug：由目标推导稳定 slug（target_slug.rs 的 kebab + 哈希截断逻辑），无 slug 时退出码 1；
• write：读取 IMPECCABLE_CRITIQUE_META 环境变量中的 JSON 元数据（critique_storage.rs），由 helper 而非调用方拥有目标指纹：会丢弃调用方传入的 target_fingerprint/target_path/target_identity 并重新解析，防止篡改。本地文件目标额外计算内容指纹 sha256:<hex>（见 fingerprint_target），使 polish 能区分"被评估的字节"与"后续编辑"，不依赖 Git 状态或时间戳；
• 快照命名与防碰撞：快照按 YYYY-MM-DDTHH-MM-SSZ[~NNNN]__<slug>.md 写入（见 now_filename_stamp），同一 UTC 秒内第二次写入通过固定宽度 ~0001 起算的碰撞后缀实现独占创建（create_new(true)），确保同一秒内的第二次 critique 不可能覆盖历史（critique_storage.rs）。测试 snapshot_name_accepts_collision_suffix 验证了命名规则；
• latest：读取最新未关闭快照，支持 --json 输出 snapshot_file 与 body；本地目标内容指纹不匹配时会自动 close 旧快照并返回退出码 2（表示"目标已变更"），防止把旧评估误当作当前状态；
• trend：按 slug（含 legacy slug 兼容路径）列出最近 N 条（默认 5）快照 frontmatter；
• close：在 frontmatter 中写入 closed: true（insert_closed_flag），用于"目标内容已变/会话关闭"时标记快照失效；会校验快照与解析目标身份匹配，避免误关。

此外，目标身份（target_identity）分为 file:<resolved-path> 与 url:<origin><pathname> 两类（critique_storage.rs），latest/close/trend 都依赖它来避免 slug 同名歧义——这一点在 pre_hash_slug_collisions_require_matching_identity 测试中有完整的碰撞场景覆盖。

9.3 趋势行的正确读法

每条趋势条目都读取 max_score：全部条目共享同一最大值时，一次性注明分母（如 out of 40）；最大值不同时逐条打印各自分母（24/32 → 30/40），并说明各次评分的启发式集合不同，该趋势线不可直接等比。旧条目缺失 max_score 按 40 处理。若是该 slug 的首次运行，趋势只有一条分数，应说明"First run for this target, no trend yet."

十、追问用户（Ask the User）：定向问题 + 最终问题门控

呈现 findings 之后，基于实际发现提出定向问题，问出无法推断的内容，这些答案将塑造行动计划。问题必须与报告同一条消息发出，报告写在前、问题在最后，不要拆成两轮——以报告结尾的一轮就是结束的一轮，问题永远不会到达。消息内顺序是关键，因为结构化问题之后的散文会被挂起直到用户作答。

可循的四类提问方向（需按具体 findings 适配，禁问泛泛问题）：

1. 优先级方向：基于发现的问题类别，让用户选先攻哪类，给出 2–3 个发现的问题类别作为选项；
2. 设计意图：若发现调性错配，问是否有意为之，给出 2–3 个可修正问题的调性方向；
3. 范围：问想修多少——"Top 3 only / All issues / Critical issues only"等选项；
4. 约束（可选）：触及面大时，问是否有禁区，防止计划碰到用户已满意的部分。

提问规则：

• 每个问题必须引用报告中的具体 finding，禁问"你们的受众是谁"这类泛问题；
• 最多 2–4 个问题；
• 给出具体选项，不要开放式提问；
• 跳过仅在报告列出的 Priority Issues 少于 3 个时允许——按数量判断，不要凭感觉认为"findings 很直接"。3 个及以上时，问题必须提出。

最终问题门控：用户可见响应要么包含定向追问（每个问题带 2–3 个绑定实际 findings 的具体选项），要么带字面行 Questions skipped: <reason>（说明允许跳过的数量）。不能只以开放式问题结尾，更不能两者皆无——"报告后什么也没问、也没打印跳过行"是这个命令最常见的失败方式。

十一、推荐动作（Recommended Actions）：从评审到行动的闭环

收到用户答案后，呈现反映其优先级与范围的优先动作清单：

1. /command-name：要修什么（带上来自 critique findings 的具体上下文）
2. ...

推荐规则：

• 只推荐白名单命令；先按用户声明优先级排序，再按影响排序；
• 每条描述携带足够上下文，让命令知道聚焦点；把每个 Priority Issue 映射到合适的命令；
• 跳过零问题的命令；用户选择有限范围则只列范围内的项；用户标记禁区则排除触碰该区域的命令；
• 只要有推荐修复，以 /impeccable polish 作为收尾步骤。

最后告知用户：

You can ask me to run these one at a time, all at once, or in any order you prefer.

Re-run /impeccable critique after fixes to see your score improve.

十二、参考材料 A：认知负荷评估（Cognitive Load Assessment）

认知负荷是使用界面所需的总心智努力。过载的用户会犯错、沮丧、离开。

12.1 三类认知负荷

类型	含义	应对策略
内在负荷（Intrinsic）	任务本身固有的复杂度，无法消除但可结构化	拆解为离散步骤；提供脚手架（模板、默认值、示例）；渐进式披露（只显示当下所需）；相关决策分组
外在负荷（Extraneous）	差设计造成的心智浪费，应无情消除	消除需要心智映射的混乱导航；模糊标签；争夺注意力的视觉杂乱；阻碍学习的不一致模式；意图与结果之间的多余步骤
相关负荷（Germane）	构建理解的学习投入，是好负荷	渐进式披露逐步揭示复杂度；一致模式奖励学习；确认正确理解的反馈；以行动而非文字墙完成 onboarding

12.2 认知负荷检查清单（8 项）

• [ ] 单一焦点：用户能否不被竞争元素干扰地完成主任务？
• [ ] 分块：信息是否以可消化分组呈现（每组 ≤4 项）？
• [ ] 分组：相关项是否视觉上聚合（邻近、边框、共享背景）？
• [ ] 视觉层级：屏幕最重要元素是否一目了然？
• [ ] 一次一事：用户能否在进入下一决策前专注单个决策？
• [ ] 最少选择：决策点可见选项是否 ≤4？
• [ ] 工作记忆：用户是否需要记住上一屏信息才能操作当前屏？
• [ ] 渐进式披露：复杂度是否只在需要时揭示？

计分：数失败项。0–1 = 低负荷（好）；2–3 = 中等（尽快处理）；4+ = 高负荷（必须修复）。

12.3 工作记忆法则

人类工作记忆同时只能容纳 ≤4 项（Miller 定律经 Cowan 2001 修正）。决策点处同时考虑的不同选项/动作/信息：

• ≤4 项：在工作记忆极限内，可管理；
• 5–7 项：逼近边界，考虑分组或渐进式披露；
• 8+ 项：过载，用户会跳过、误点或放弃。

落地应用：动作按钮 1 主 + 1–2 副，其余收入菜单；导航 ≤5 个顶层项；长文单条阅读路径，关联链接收拢到文末单一区块；文档侧边栏每层可见兄弟项 ≤4；作品集/画廊索引每屏一个决策，而非滤镜+排序+标签一拥而上。

12.4 常见认知负荷违规（八种）

#	名称	问题	修复
1	The Wall of Options	10+ 选择无层级地一屏摊开	分类、高亮推荐、渐进式披露
2	The Memory Bridge	必须记住步骤 1 的信息才能完成步骤 3	保持相关上下文可见，或在需要处重复
3	The Hidden Navigation	用户必须建立心智地图	始终显示当前位置（面包屑、激活态、进度指示）
4	The Jargon Barrier	技术/领域语言迫使翻译	用平实语言；领域术语不可避免时内联定义
5	The Visual Noise Floor	每个元素视觉权重相同，无焦点	建立明确层级：1 主、2–3 次、其余弱化
6	The Inconsistent Pattern	相似动作在不同位置行为不同	标准化交互模式：同型动作 = 同型 UI
7	The Multi-Task Demand	界面要求同时处理多个输入（读+决策+导航）	排序步骤，一次只做一件事
8	The Context Switch	为单个决策在屏/标签/弹窗间跳转	将决策所需信息就近聚合，减少来回

十三、参考材料 B：Nielsen 启发式评分指南（Heuristics Scoring Guide）

以 0–4 分给 Nielsen 的 10 条可用性启发式逐条打分。要诚实：4 分意味着真正出色，不是"够用"。以下是完整评分准则（各条均含检查项与 0–4 评分标准，可直接用于报告表）。

1. Visibility of System Status

检查项：异步操作加载指示；动作确认（保存/提交/删除）；多步流程进度指示；导航中的当前位置；内联表单校验反馈。 评分：0 无反馈，用户靠猜；1 罕见反馈；2 部分传达、重大缺口；3 大多数操作有清晰反馈、小缺口；4 每个动作都有确认、进度始终可见。

2. Match Between System and Real World

检查项：熟悉术语（无未解释黑话）；符合用户预期的逻辑信息顺序；可识别的图标与隐喻；面向目标受众的领域化语言；自然阅读流（左到右、上到下优先）。 评分：0 纯技术黑话；1 大多令人困惑，需领域专长；2 混合，部分黑话泄漏；3 大多自然，偶有术语需语境；4 全程流利说用户语言。

3. User Control and Freedom

检查项：撤销/重做；表单与弹窗的取消按钮；返回安全的清晰导航；清除滤镜/搜索/选择；长流程或多步流程的退出。 评分：0 困住用户，除刷新外无出路；1 出路难找；2 部分出口，主流程有、边界无；3 控制良好，可退出并可撤销多数动作；4 全控制，处处有撤销/取消/返回/退出。

4. Consistency and Standards

检查项：术语一致；同动作处处同结果；遵循平台惯例；视觉一致（颜色、字体、间距、组件）；交互模式一致（同手势 = 同行为）。 评分：0 处处不一致，像拼贴产品；1 大量不一致；2 部分一致，主流程吻合、细节分歧；3 基本一致，偶有偏差但无混淆；4 完全一致的连贯系统。

5. Error Prevention

检查项：破坏性动作前确认；约束防止非法输入（日期选择器、下拉）；减少错误的智能默认值；防误解的清晰标签；自动保存与草稿恢复。 评分：0 错误易犯，无护栏；1 防护稀少；2 部分预防，常见错误被拦、边界漏网；3 良好预防，多数错误路径被主动阻断；4 通过智能约束几乎杜绝错误。

6. Recognition Rather Than Recall

检查项：选项可见（不埋在隐藏菜单）；情境帮助（tooltip、内联提示）；最近项与历史；自动补全与建议；图标带标签（非纯图标导航）。 评分：0 重度记忆依赖；1 多为回忆，隐藏功能多、可见线索少；2 部分辅助，主动作可见、次功能隐藏；3 良好识别，大多可发现、记忆负担少；4 一切可发现，无需记忆。

7. Flexibility and Efficiency of Use

检查项：常用动作键盘快捷键；可定制界面元素；最近项与收藏；批量操作；不复杂化基础路径的高级用户功能。 评分：0 单一路径无捷径；1 灵活性有限；2 部分快捷键、基础键盘支持；3 良好加速器，键盘导航、部分定制；4 高度灵活，多路径、高级功能、可定制。

8. Aesthetic and Minimalist Design

检查项：每步只显示必要信息；引导注意力的清晰视觉层级；颜色与强调的有目的使用；无争夺注意力的装饰杂物；聚焦、不杂乱的布局。 评分：0 压倒性，一切同等抢眼；1 杂乱；2 部分杂乱，主内容清晰、边缘嘈杂；3 基本干净，微小视觉噪声；4 完美极简，每个像素都挣得价值。

9. Help Users Recognize, Diagnose, and Recover from Errors

检查项：平实语言错误消息（不给用户错误码）；具体问题定位（"Email is missing @" 而非 "Invalid input"）；可执行的恢复建议；错误显示在问题来源附近；非阻断式错误处理（不清空表单）。 评分：0 晦涩错误；1 含糊错误（"出错了"且无指引）；2 清楚但不帮上忙（指出问题但没给修法）；3 清楚且带建议；4 完美恢复：定位问题、给修法、保留用户工作。

10. Help and Documentation

检查项：可搜索帮助/文档；情境帮助（tooltip、内联提示、引导）；任务导向组织（非功能导向）；简洁可扫读；无需离开当前语境即可访问。 评分：0 任何地方都没有帮助；1 帮助存在但难找或无关；2 基础帮助（FAQ 或文档存在但不情境化）；3 良好文档，可搜索、基本任务导向；4 出色的情境帮助，正确时刻给出正确信息。

13.1 分数汇总与评级区间

总分上限 40（10 条 × 4）。注意：这是"全部适用"时的满分，实际报告表用适用最大值归一化。

Score Range	Rating	含义
36–40	Excellent	只需小修，可以发布
28–35	Good	补短板即可，基础扎实
20–27	Acceptable	需显著改进用户才会满意
12–19	Poor	需要大改核心体验
0–11	Critical	需要重新设计，当前状态不可用

当存在 n/a 条目时最大值低于 40，应按百分比读档位而非原始数字（90%+ Excellent、70%+ Good、50%+ Acceptable、30%+ Poor、以下 Critical）。24/32 即 75%，属于 Good。

13.2 问题严重度（P0–P3）

Priority	Name	Description	Action
P0	Blocking	完全阻止任务完成	立即修复；这是 showstopper
P1	Major	造成显著困难或困惑	发布前修复
P2	Minor	恼人但有变通方案	下一轮修
P3	Polish	可修可不修，无真实用户影响	有时间再修

判断技巧：拿不准两个级别时问自己："用户会不会为此联系客服？"会，则至少 P1。

十四、参考材料 C：Persona 化设计测试（Persona-Based Design Testing）

用 5 个不同的用户原型测试界面，每个原型暴露单一"设计总监"视角会漏掉的失败模式。用法：选 2–3 个与当前界面最相关的 Persona，以每个 Persona 走一遍主要用户动作，报告具体红旗而非泛泛担忧。

14.1 五个预置 Persona

1. 急躁高级用户 "Alex"：同类产品专家，期待效率、讨厌手把手，找不到捷径就离开。行为：跳过所有 onboarding 与说明；立即找键盘快捷键；尝试批量选择/编辑/自动化；被不必要步骤激怒；任何迟缓或说教都会让其放弃。测试问题：60 秒内能否完成核心任务？常用动作有快捷键吗？onboarding 能完全跳过吗？弹窗有 Esc 关闭吗？有"高级路径"吗？红旗：强制教程或不可跳过 onboarding；主动作无键盘导航；不可跳过的慢动画；本可批处理却一次一项的流程；低风险动作的多余确认。

2. 困惑新手 "Jordan"：从未用过此类产品，每步都需要引导，宁可放弃也不自己摸索。行为：仔细读所有说明；对陌生点击犹豫；不断找帮助；误解术语缩写；对标签做最字面解读。测试问题：5 秒内首个动作是否显然？所有图标都有文字标签吗？决策点有情境帮助吗？术语是否假定先验知识？每步都有清晰的"返回/撤销"吗？红旗：无标签纯图标导航；无解释的技术黑话；无可见帮助或引导；完成动作后下一步不明确；无动作成功确认。

3. 无障碍依赖用户 "Sam"：使用读屏（VoiceOver/NVDA）、纯键盘导航，可能低视力、运动或认知差异。行为：线性 Tab 遍历；依赖 ARIA 标签与标题结构；看不到 hover 或纯视觉指示；需要足够对比度（文本 4.5:1 最低）；可能放大到 200%。测试问题：主流程能否纯键盘完成？所有交互元素可聚焦且有可见焦点指示？图片有有意义的 alt？对比度符合 WCAG AA？读屏会播报状态变化（加载/成功/错误）？红旗：无键盘替代的纯点击交互；缺失或不可见焦点指示；纯颜色传达含义（红=错、绿=对）；未标记表单字段或按钮；无延期选项的限时动作；破坏读屏流程的自定义组件。

4. 审慎压力测试者 "Riley"：方法论的用户，把界面推过快乐路径，测边界、试意外输入、探测体验缺口。行为：故意测边界（空态、长字符串、特殊字符）；提交意外数据（emoji、RTL 文本、超长值）；通过后退、刷新、多标签破坏工作流；找 UI 承诺与实际行为的不一致；有条理地记录问题。测试问题：边界处会发生什么（0 项、1000 项、超长文本）？错误态能优雅恢复还是留下坏 UI？中途刷新是否保留状态？有没有看似能用却产出坏结果的特性？UI 如何处理意外输入（emoji、特殊字符、粘贴 Excel）？红旗：看似能用却静默失败或产错；暴露技术细节或留下坏状态的错误处理；无用的空态（"无结果"且无指引）；刷新/导航丢数据的工作流；不同位置相似交互行为不一致。

5. 分心移动用户 "Casey"：单手在路上用手机，频繁被打断，可能在慢连接上。行为：只用拇指，偏好底部操作；中途被打断后返回；频繁切换应用；注意力短、耐心低；尽量少打字，偏好点选。测试问题：主动作在拇指区（屏幕下半）？离开再返回是否保留状态？慢连接（3G）下可用？表单能用自动补全与智能默认值？触摸目标 ≥44×44pt？红旗：重要动作在屏幕顶部（拇指够不到）；无状态持久化，切换即丢进度；本可用选择代替的大文本输入；每页加载重资产（无懒加载）；过小或过近的触摸目标。

14.2 选择 Persona

Interface Type	Primary Personas	Why
Landing page / marketing	Jordan, Riley, Casey	第一印象、信任、移动
Dashboard / admin	Alex, Sam	高级用户、无障碍
E-commerce / checkout	Casey, Riley, Jordan	移动、边界、清晰
Onboarding flow	Jordan, Casey	困惑、打断
Data-heavy / analytics	Alex, Sam	效率、键盘导航
Form-heavy / wizard	Jordan, Sam, Casey	清晰、无障碍、移动

14.3 项目特定 Persona

当 AGENTS.md 含 impeccable init 生成的 ## Design Context 节时，从受众与品牌信息派生 1–2 个额外 Persona：① 阅读目标受众描述 → ② 找出 5 个预置 Persona 未覆盖的主要用户原型 → ③ 按模板创建：

##### [Role]: "[Name]"

**Profile**: [2-3 key characteristics derived from Design Context]

**Behaviors**: [3-4 specific behaviors based on the described audience]

**Red Flags**: [3-4 things that would alienate this specific user type]

只在有真实 Design Context 数据时生成；不要虚构受众细节；无上下文时使用 5 个预置 Persona。

十五、与仓库实现的对照速查

文档要素	仓库实现
CLI 入口 shim	.pi/skills/impeccable/scripts/impeccable（skill/scripts/impeccable 为同源脚本）
critique-storage 五个子命令（slug/write/latest/close/trend）	crates/context/src/critique_storage.rs
slug 推导（kebab + SHA-256 截断，SLUG_MAX=50）	crates/context/src/target_slug.rs
元数据环境变量 IMPECCABLE_CRITIQUE_META	crates/context/src/critique_storage.rs
内容指纹与目标身份（file:/url:）	crates/context/src/critique_storage.rs
快照命名与碰撞后缀 ~NNNN	crates/context/src/critique_storage.rs
命令描述元信息	skill/scripts/command-metadata.json
命令路由总览	skill/SKILL.src.md（critique [target] 表目）

在仓库对应的宿主目录（.pi、.claude、.cursor、.gemini、.github、.grok、.trae、plugin/skills、skill 等）下，该文档均有同源副本，命令脚本统一通过 .pi/skills/impeccable/scripts/impeccable 形式调用。一次完整的 critique 运行 = 解析稳定目标 → 双 Agent 隔离评估 → 编织综合报告 → 聊天交付 → 快照持久化（含指纹防串档）→ 定向追问 → 依回答给出命令动作清单，并以 /impeccable polish 承接优先问题完成闭环。