spec-leak-review

Spec Leak Review

流程类 Skill，仅在用户显式调用 $spec-leak-review 时运行。默认审查后直接修复被审文件，再复验并生成 HTML，不询问是否修复或是否需要 HTML。用户明确要求只读时只审查；明确要求只要文字或不要 HTML 时改为 Markdown。先按对象的用途选择证据模式：

• 文本模式：长期规范、提示词、配置、日志、纯文本讲者备注等。以文件或用户提供的原文为证据，采集与定级无需浏览器或截图；生成 HTML 后仍验证报告的浏览器展示。
• 视觉模式：网站、网页应用、PPT/幻灯片（包括 HTML、PDF 或图片形式）及其中的比较页面。必须逐页真实看图，不能因为 HTML 可读源码而降为文本模式。用目标格式的渲染工具获取画面；用户提供的截图也可作为已覆盖部分的证据。

混合输入分别记录，例如幻灯片走视觉模式、独立备注走文本模式。报告开头写明模式、输入版本/哈希、实际页数/界面状态、受众和覆盖范围。视觉采集失败时保持视觉模式并记录缺口。默认通过 $review-html-report 生成单文件 HTML，保留审查记录与视觉采集、标注截图。

1. 确定受众与决策

先回答三件事并写进报告开头：谁会阅读或打开目标；带着什么疑问来；看完之后要做出什么决定或动作。文本模式中的“受众”可以是执行该文档的 agent、维护 Skill 的作者或文档读者；视觉模式中的“受众”是页面用户或演讲观众。

受众决定一切判定——同一句“清单摘要 975d85…”对终端用户是噪音，对值班运维是工作对象。无法从用户输入、目标文件、网站上下文或代码判断受众时，先问用户，不要假设后展开审查。

完成标准：受众和“看完要做的决定”各能用一句话说清，且后续每条 finding 都能挂回其中一句。

2. 建立证据清单

文本模式

逐个读取用户指定的文本；没有指定文件时，只扫描任务范围内的文本，不把二进制或依赖目录当成证据。保留原文、文件路径和行号（必要时给出段落或字符范围），并记录文件用途、预期读者和是否由配置/模板生成。多文件交叉引用时以实际引用链为准，不凭目录名推断。

重点标出这些提示词残留：面向模型的会话开场、角色扮演、一次性用户请求、对当前对话的指代、隐藏推理或“请先……再……”的临时编排、把宿主/调用方式复述进正文的元说明，以及与文档任务无关的用户背景。提示词语气本身不是问题：Skill 的操作步骤、约束和安全门槛只要服务于预期读者，就属于正文。

完成标准：每个被审文件都有用途、读者、覆盖行数和证据位置；每条 finding 都能回指原文行号或明确标注为用户提供的片段。

视觉模式

双轨采集，两轨都有时交叉核对。

截图轨：用 scripts/capture-surface.js 或目标格式渲染器采集每个页面/幻灯片。脚本生成真实截图、文档坐标 bbox 的 DOM 文本清单及 surfaces 绘制面清单；后者包括图片、canvas、SVG、背景图、嵌入页等需单独看图的区域，不含位图文字识别。title/aria-label 属于辅助属性，不能直接当作当前画面已显示的文案。脚本非零退出、错误页、失败图片都要记录缺口；采集成功也不代表完成审查。

真正打开每一张截图看图，按区域盘点标题、副标题、说明、卡片、字段、状态、按钮及位图内文。surfaces 是补充盘点入口；图中存在而清单未捕获的区域（如 iframe 内部、伪元素或复杂合成）手工补入。对每个承载文字/证据的位图记录截图/素材、页与 bbox、实际读到的原文及用途；alt、OCR 和 DOM 清单只作线索，须回图核对。不可辨认处记录范围与原因，不凭上下文补写。

在实际投影视口看整页，再看重要局部。逐页记录已打开的图、视口、具体观察、位图覆盖及缺口；关键制作说明或证据不能因小字而免审。拿不到浏览器时可以使用用户已有截图，未覆盖的页/状态仍保留在总数中。

代码轨：用截图里的文案原文在仓库检索定位组件与 i18n 条目，比按目录猜更可靠；每条给出 file:line。截图未出现的错误态、空态、tooltip、loading 等分支文案一并纳入清单。文案有配置或环境变量覆盖机制时，确认线上生效值，不拿源码默认值当结论。

截图里有而代码里检索不到的，标注来源为运行时数据或后端返回。部分区域因鉴权、外部网关或无法构造触发条件而采集不到时，如实记录范围和原因，不用源码推断冒充渲染结果。

对展开、tooltip、幻灯片导航、比较切换等无写入交互，实际操作后再看图并记录步骤、状态与结果；嵌入画面的真实内容和图注/结论是否对应一并核对。不能安全触发的状态记未覆盖，不根据控件存在推定完成。