ux-audit

ux-audit — 场景审计循环

属于 super-ux — 整个流程和四条同步规则见 system-map.md。 开始任何审计前，先运行检查器（python3 docs/ux/lint.py）——它能免费发现结构漂移， 省去后续代码追踪检查的麻烦。

验证代码是否真正实现了 docs/ux/scenarios.md 中的每个场景：每个步骤都可到达、每个按钮都存在、每种状态都得到处理、每个错误都如实呈现。输出：在 docs/ux/audits/ 中生成带版本号的报告，并更新基准中的审计状态。

格式约定：scenario-format.md （ux-contract v4）——报告结构、结论（PASS / PARTIAL / FAIL / BLOCKED）、严重程度。

在确定范围后再计算前置条件，每轮检查一个——绝不一刀切地停止。 每种范围都需要自己的输入；如果项目具备某种输入但不具备其他输入，就运行它能够执行的检查：

• 场景范围需要 docs/ux/scenarios.md；如果文件不存在，本轮检查就没有可据以审计的内容——先运行 ux-scenarios 技能，或者在用户提出**“no scenarios”** / **«без сценариев»**时，审查现有内容并说明这一点。
• 文案范围只需要品牌包（docs/brand/voice.md）；只有品牌资料、没有场景的独立博客，可以进行文案审计，而不运行其他检查——不会被要求创建它用不上的场景。
• 基准范围需要已观察到的竞品 URL 及其采集凭据，而不是场景基准。

因此，在只有品牌资料的项目上运行 /ux-audit copy，会审计文案；运行 /ux-audit all 时，如果没有 docs/ux/scenarios.md，则会执行输入齐备的检查，并在报告中说明场景方面的限制，而不是停止整个流程。

**完整上下文：**如果存在 docs/ux/foundation.md，请结合每个场景的关联链进行审计——加载已追踪故事的验收标准（Given/When/Then）作为额外检查，并注明实现是否真正满足了任务和旅程阶段的需求，而不只是渲染界面元素。即使流程中的所有按钮都存在，如果任务结果无法达成，结论至多为 PARTIAL。如果存在 docs/ux/flows.md，还要验证代码是否实现了流程图：每个节点都可到达、每条边（包括错误边）都已接通、流程表中的屏幕状态都已实现——未实现的节点或边应作为已追踪场景的发现项。

触发词

会将请求路由至此技能的英文和俄文短语。为控制技能列表的长度（2026-10-20），描述中仅保留最具代表性的短语；系列路由钩子与此列表一致。

"ux audit" / "UX-аудит"、"run the scenarios" / "прогони по сценариям"、"check all buttons/states/errors"、发布前 UX 验证、场景合规性检查。

文案范围（copy）

单次通过，与 python3 docs/brand/lint.py 配套：lint 程序验证品牌规范的机械性部分，本范围评估需要读者判断的部分。需要 docs/brand/voice.md；没有记录好的品牌规范，就只能凭感觉评判，因此应转到 /brand-init。

本范围读取的内容：brand-contract.md，用于了解品牌规范的文件名和字段名；voice-packs.md，用于用品牌规范自身的措辞命名失效模式；surface-registers.md，用于了解各个表面应采用的语域；以及 ai-tells.md，用于进行“与其他 SaaS 无异”测试。

检查项	问题	证据
语气偏移	这个表面听起来像记录在案的品牌语气，还是像撰写者本人的语气？	字符串或段落，file:line
与其他 SaaS 无异测试	这句话能否原封不动地出现在竞争对手的页面上？	该句
所以呢	每项功能是否都说明了会带来什么结果？	缺少衔接的主张
证明	每项主张附近是否都有佐证？	该主张及缺失的事实
叙事	主视觉、对手和承诺在各个表面上是否一致？	存在分歧的两个表面
失效模式	品牌语气是否过度，滑向品牌规范声明的退化形式？	该段落，参照品牌规范自身的措辞命名
语域	该表面是否符合 channels.md 中的记录？	记录和文案

与其他范围一样，判定为 PASS / PARTIAL / FAIL / BLOCKED，并为每项附上 file:line。发现项沿用相同的修复计划流程。报告 lint 程序的发现项，但不要重复列出：lint 结果干净表示“可检查”，不代表“质量好”；同时运行两者的意义就在于此。

基准测试范围（benchmark:<competitor>）

其他每种范围都会根据产品自身的流程链进行衡量，无法报告整个流程比其他产品多出两步。本范围则针对指定的竞争对手进行衡量，且只评估从外部可以观察到的内容——绝不猜测对方的代码。

在相同维度上衡量双方，并说明数字的来源：

维度	记录内容
首次获得价值所需时间	从进入页面到获得第一个实际成果所需的分钟数，按 BP-149 的细分群体预期统计
激活所需步骤	在获得该成果之前需要经过的页面和填写的必填字段
入门成本	是否需要银行卡？是否需要账户？不满足任一条件时能访问什么内容？
关键流程深度	我们和对方最重要的那条流程分别需要几步
首次运行引导	空状态提供什么（BP-152），引导流程会教什么
移动端	商店评分、近期评价中的主要好评和主要差评

应用商店和客服评价是双方最便宜、最可靠的信号：将近期评价归类为好评、功能请求、Bug 和摩擦问题。竞争对手的摩擦问题正是可以超越对方之处；我们自己的问题应作为痛点纳入用户旅程（ux-foundation），并注明来源和日期。

像其他检查项一样报告发现，但判定结果要单独列出：与竞争对手之间的差距是一个机会，而不是相对于场景的缺陷——它应成为基础文档中的一个故事，而不是本报告中的一项修复。

证据规范（不可妥协）

每项判定都必须引用与主张类型相符的证据。关于本代码库的主张，引用 file:line。关于外部数据的主张——例如基准测试中的竞争对手、实时第三方页面——引用 URL + 时间戳 + 截图或保存的响应，因为竞争对手的流程在你的代码库中没有 file:line，捏造一个就是伪造引用。找不到或无法验证某项内容？判定为 BLOCKED，并说明确切原因——绝不猜测，绝不为了客气而判定 PASS，基准测试也绝不为外部观察捏造本地 file:line。只会吹捧代码库的审计毫无价值。

覆盖率指标是一项检查，而它的匹配规则隐藏着假设

指标旨在终结关于覆盖率的争论：它读取文档，将其与代码匹配，然后发布一个数字。接着，人们发现，决定文档描述对象的规则不过是一行字符串处理代码，而这个数字却把已有的工作报告为缺失的工作。这个数字如今制造了工作，而这些工作是虚构的。

实测情况：一份屏幕清单将某个场景在 Entry point: 中把路径列为主要入口点（第一个带反引号的路径）时，判定该屏幕已有文档记录。提取时原样保留了该路径，因此，两个场景在描述对象时带有查询字符串——`/reset-password?token=…` 和 `/account/billing/return?invoice=&status=`——都没有匹配到路由，**两块一直有文档记录的屏幕被报告为完全没有场景。**随后，面板列出了九块需要补充场景的屏幕。其中两块根本不需要补充；第三块是一个组件对应两个地址，而这条规则只能识别其中一个。九行中有三行是虚构的，而这个数字的全部意义，本是避免人们凭记忆争论覆盖率。

因此，对于这些文档上的任何指标：

• **判断描述对象的规则必须是一个具名的导出函数，并附带一组模拟输入的测试表——包括负面用例。**查询字符串、片段、同一字段中的多个路径，以及完全没有反引号的文字。它还是内联正则表达式时，无法测试，这正是它从未接受测试的原因。
• 如果指标无法表达某种实际状态，就应在数字旁说明这一点，而不是将该状态算作失败。一个屏幕对应两个地址，仍然是一个屏幕；矩阵会另列一行派生的别名路由，而不是悄悄将第二个地址评为没有文档记录。
• **这条规则是经过深思熟虑、来之不易的，这正是应该测试它，而不是信任它的理由。**这条规则曾两次取代更宽松的规则，每次都是因为有人仅凭提及而非描述对象，就报告某个屏幕已覆盖。有着这种历史的规则，恰恰最没人会重新审视。

深度级别

各轮检查的深入程度、每个级别读取的内容，以及会引用哪些资料： references/audit-depth.md。

循环

1. 范围。 阅读 base（以及存在时的 foundation/flows）。如果提供了 $ARGUMENTS，则范围为 $ARGUMENTS（all、feature:<name>、SCN-010..SCN-020、coverage、practices、heuristics、copy、benchmark:<competitor>），默认值为 all；深度关键词（quick/deep）用于选择深度，默认值为 standard。单次运行范围（coverage/practices/heuristics/copy/benchmark:<competitor>）只运行对应的检查。记录 docs/ux 的 git SHA——将其写入报告标题。跳过 retired 场景。
2. 分批。 按功能将范围内的场景分组，每批约 5–8 个。开始前列出各批次，以便查看进度。
3. 审查每个批次。 对于大型范围，使用可用的子 Agent 并行处理，每个子 Agent 负责一个批次。未委派时，按相同批次顺序依次审查；两种方式都应返回逐场景判定，并提供相同的证据。 证据分为三个层级，判定必须注明所依据的层级——因为 file:line 只能证明实现中的文本，不能证明用户能到达该处。静态符合性（file:line——代码如此声明）、可执行验证（测试或浏览器凭证——运行时确实如此），以及生产观察（来自真实环境的信号——写入第 7 步的 Product:，绝不能写入审查结果）。每项标准都标记为 STATIC 或 RUNTIME：
   • 入口点存在（STATIC），且用户能够访问（RUNTIME——CSS 覆盖层、身份验证、网络限制都可能隐藏一个已存在的路由）；
   • 每个编号步骤都有实现路径（STATIC）；
   • 每个列出的 UI 元素都存在（STATIC），且已连接到一个会在用户点击时实际触发的处理程序（RUNTIME）；
   • 每个列出的状态（loading / empty / error / success）都有对应的渲染分支（STATIC）——完整的状态分类及其压力测试行见：state-stress-matrix.md；
   • 每个列出的错误都如实呈现给用户（RUNTIME——代码中存在分支，并不能证明用户看到了错误）；
   • 预期结果确实可观察到（RUNTIME）。 RUNTIME 标准只有在有测试、浏览器检查或已验证的运行时凭证时才可判定为 PASS——没有这些证据时，应判定为 BLOCKED（未验证），绝不能仅凭 file:line 判定为 PASS，也绝不能在没有浏览器可用时凭空编造证据。浏览器检查先在 WebKit（Safari）中运行，并注明其引擎（browser-engine.md）。STATIC 标准可凭其 file:line 判定为 PASS，并注明证据类型。任何缺口 → PARTIAL（若流程缺失或损坏，则为 FAIL），并附上问题 [AUD-YYYY-MM-DD-NN] (severity) description -> suggested fix。
4. 在报告形成统一结论前，交叉核对各批次。 各批次独立运行——在大型范围中，由彼此不可见的子 Agent 并行执行——而第 5 步和第 6 步会将其汇总为一份报告和摘要。这是一个汇合过程，而汇合会信任已经到达的输入。需要检查以下四点：
   • 同一根因对应多个问题 ID——三个批次发现了同一个缺失的错误分支，应视为一个修复项和三条记录，而这三条记录会分摊其优先级。
   • 两个批次对同一屏幕给出矛盾结论——同一元素在一个批次中是 PASS，在另一个批次中是 FAIL。其中一个结论必然有误，而报告无法判断是哪一个。
   • 某个批次没有返回任何结果，但其场景涉及另一个批次标记的问题所在屏幕。在摘要中，空结果与未运行的批次看起来完全一样。
   • 某项判定的证据弱于相邻项——例如，基于阅读差异得出的 PARTIAL，与基于浏览器检查得出的 FAIL 并列呈现，却被赋予相同的权重。 以任一种方式撰写答案：跨批次：无问题，或者列出相互矛盾的项，并给出解决它们的裁定。某项检查若没有任何输出，导致无法区分它是未运行还是运行后无结果，就不能作为证据。场景库在上一层已经包含相同机制——ux-scenarios 第 4 步，相互矛盾的场景——这里是将其应用于审计自身的输出。
5. 撰写报告，按约定写入 docs/ux/audits/YYYY-MM-DD[-scope].md，并随着结果到达逐批写入——运行崩溃时，已完成的批次必须仍保存在磁盘上。
6. **撰写摘要。**列出总数、主要问题（先列对用户伤害最严重的）和按优先级排序的建议行动。摘要必须能独立阅读，让不会查看批次详情的人也能看懂。
7. **更新基准——仅更新交付状态。**为每个已审计场景更新 Last audit 列（YYYY-MM-DD VERDICT）；仅当场景所依赖的每项 RUNTIME 标准都有可执行证据或运行时回执证据时，才将 validated → implemented；带有未经验证的 RUNTIME 标准的场景仍须保持 validated，并将这些标准标记为 BLOCKED，因为静态 PASS 交付的是代码的文本，而非用户的结果。若场景的所有标准都是 STATIC，则可以在记录证据类型后将其设为 implemented。审计期间绝不改动场景内容。审计绝不填写 Product:。PASS 表明代码实现了场景所述内容——这是交付证据，却不能证明上线该场景对任何人产生了影响。只有收到来自现实世界的信号，结果状态才会改变；审计会产出两样彼此不同的东西：一个 file:line 和审计自身的判定。U068 拒绝将两者都视为结果信号，因此走捷径不仅违反本指示，也无法通过门槛。审计后状态为 implemented 且 unobserved 的场景，属于正确且完整的记录，而不是本步骤需要补上的缺口；报告若将一个 PASS 场景称为“产品未经验证”，说的就是实情。
8. **制定 UX 计划。**获得用户同意后，按约定的 UX 计划格式，将 FAIL/PARTIAL 发现转化为 docs/ux/plans/YYYY-MM-DD-<scope>.md：为每个受影响的屏幕列出目标界面（元素、状态、行为），并附上 CREATE/MODIFY/DELETE 变更表；每一行都须关联到场景/流程/发现/原则 ID，并按 Frequency × Severity × Solvability 排序（先处理对用户伤害最严重的，而非最容易实现的差异）。
9. **提供自主执行选项（建议，不强迫）。**明确说明用户现在已获得的内容——此计划、审计报告、docs/ux/ 链路和 Figma 画面——并说明是否继续由用户决定。然后建议使用 ssheleg task-pipeline 插件，按最佳实践端到端实现该计划：
   • 已安装 → /task-pipeline docs/ux/plans/<file>（不要自动运行——先征求同意）；
   • 未安装 → 提供一次性安装命令，并说明它是可选的： /plugin marketplace add ssheleg/task-pipeline → /plugin install task-pipeline@task-pipeline；
   • 用户有其他偏好 → 使用 superpowers writing-plans → 子 Agent 执行，或手动完成——都可以。 计划本身可在没有本次对话的情况下执行，因此任何路径都可行。无论用户选择哪种方式，都要提醒：同一变更规则仍然适用，完成后重新运行 /ux-audit <scope> 确认 PASS。

PASS 语义

启发式（PRN-NN）和实践（BP-NNN）发现均为建议——属于改进机会，绝不构成阻碍；除非违反项导致场景无法成立（此时它是该场景上的常规发现），否则不会改变场景判定。实践是协议选出的改进机会，并非风格门槛。

实时检查与视觉偏差

如果项目有可运行的开发服务器，且浏览器工具可用， 请在静态检查后实时重放关键场景：像用户一样逐步操作，截图或转录实际渲染的内容，并将观察到的证据附到判定中。先用 WebKit 检查——通过 safaridriver 使用 Safari，或使用 Playwright 的 webkit；Chromium 仅作为明确说明的备选方案 （browser-engine.md）。当实时证据与静态证据不一致时，以实时证据为准。默认关闭；工具可用时可主动提供——对于品牌和旗舰界面，则默认主动提供，无需询问：导演记录或任务简报中的 surface_class: flagship 或 ad，或未记录类别时的落地页、引导页、付费墙或商店页面。

对于有 Figma 画板的屏幕，实时检查还会比较两张图片。在画板对应的状态、视口和主题下捕获构建内容，并提供 sheleg-design 的 VISUAL_REVIEW.md 要求的捕获记录 （revision、route、state、viewport、theme、motion、captured-at、source、engine），同时对画板调用 get_screenshot。用户能看到的差异属于 visual-drift 发现，按区域 → 缺陷 → 修复的格式记录： [AUD-…] (major) visual-drift SCR-03/empty @ 375·dark — illustration area → frame shows the prompt card, build shows a bare "No data" → render the card。 如果捕获结果不符合 VISUAL_REVIEW.md 的有效性要求（空白、过时、状态错误、字体未加载），或完全没有捕获，则比较状态为 BLOCKED （未验证）——绝不能判为 PASS。该状态没有画板时，无需比较。

完成标准

• 每个纳入范围的场景都有判定和证据，或有明确的 BLOCKED 原因——不得默默跳过任何场景。
• 填写范围和限制——涵盖了什么、遗漏了什么及原因、哪些内容无法验证、代码无法回答什么。批量审计只读取部分内容；如果报告对其余部分只字不提，就会被理解为已覆盖全部内容。
• 明确给出判定——REFINE（修复发现项）/ REDESIGN（发现项集中在一种无法通过修补达成目标的结构上；指出该结构）/ NEW （现有流程未描述已构建的内容；从上游重新开始）。只列发现项会被当作待办清单，而本应重建的界面会被一次一个真实发现项地无限修补下去。
• 报告已保存到磁盘，摘要准确，基础状态已更新。
• 将发现项提交给规划；不得隐去任何内容。

references/ 中还有什么。 此技能直接引用了 8 份契约；references/ 中有 24 份，因为此技能引用的契约还会链接其他契约，而且整个依赖闭包都会随技能一起分发——skills CLI 只安装一个目录，否则兄弟目录中的文件就会成为悬空引用。打开此处列出的契约；其余契约会在相关契约引导时按名称找到。