产品真相
一个展示了产品做不到的事情的产品视频,比没有视频更糟糕。在制作这些技能的生产流程中,代价最高的时刻都是真实性失败:一个手工制作的徽章,尺寸和产品名称都是错的;一个被叙述为“等待通话结果”的工作流,而产品只通过一个单独的触发器返回结果;一个被重贴标签为已确认预订的测试电话,但没人做端到端验证;一份公司文档的标题与团队已同意的定位相矛盾。每一个问题都是在后期由评审者发现,并导致了一个版本的返工。
此技能让检查变得明确和机械化:每一句旁白和每一个画面都在 TRUTH.md 中有一个对应的行和源引用,而 truth_check.py 会拒绝任何缺少、过时或无依据的行。
输入
videos/<video>/audio/lines.tsv(叙述文本,每句话一个行 ID)videos/<video>/SOURCES.md(来自 source-recon:画面及其对应代码)videos/<video>/BRIEF.md、COVERAGE.md、CLAIMS.md(视频必须解释的内容、定位、应避免的措辞、需要批准的声明)product.yaml:positioning、never_say、names(规范名称到遗留字符串的映射)、banned_termssources/<role>/和sources.lock(由 source-recon 锁定;如果缺失,先运行 source-recon,因为引用必须指向锁定的提交)
1. 列出声明
将 lines.tsv 中的每一行拆解成其做出的声明。例如,“Acme Tasks 读取你的日历并将过期任务移到明天”包含两个声明:它读取日历,以及它移动过期任务。此外,根据 SOURCES.md 和章节,为每个画面和屏幕上的操作添加一个声明(例如,“点击‘计划我的一天’会打开带有三个建议的计划器”)。
写下这些声明所引发的问题,措辞要能让代码回答:是什么触发了这个?存储了什么?有哪些选项?用户在哪里看到什么?哪些操作仅发生在服务器上?
2. 从代码和文档中回答它们
并行启动只读子代理,每个产品领域一个(前端行为、每个后端、文档),使用 references/product-facts-prompt.md 中的提示。将它们指向 sources/<role>/,切勿指向用户的检出目录,这样它们的行号才能与锁定的版本一致。它们只能从代码或文档中回答,引用每个事实,并在无法找到时说“未找到”。
3. 对每个声明进行分类
| 可见性 | 含义 | 视频可以 |
|---|---|---|
ui | 由前端渲染;引用模板或 i18n 行 | 展示它并叙述它 |
backend | 在服务器上为真,屏幕上没有任何显示 | 叙述它,但绝不为它绘制 UI |
docs | 只有文档这么说 | 引用文档 URL 叙述它;同时在可能时检查代码是否同意 |
mock | 一个设计素材,非产品 UI(如电话屏幕、结束卡、生成文本) | 展示它,但在 BRIEF 中标记为设计素材 |
| 结论 | 含义 |
|---|---|
backed | 来源明确支持此说法 |
approved | 需要签核(受限、未发布、或 CLAIMS.md 列出的声明),且评审者在 CLAIMS.md 中已批准 |
needs-approval | 真实,但受限、被门控、未发布或在 CLAIMS.md 中列出;等待评审者 |
rewrite | 部分真实;你在备注中提出有依据的措辞 |
cut | 不真实,或未找到来源 |
unbacked | 尚未检查 |
mock | 仅适用于可见性为 mock 的情况 |
只有 backed 和 approved 能通过叙述行的检查。受限功能(仅对某些角色、计划或内部团队可见)、功能开关后的功能或未合并分支上的功能,在评审者在 CLAIMS.md 中确认同意之前,均为 needs-approval,且 BRIEF 中需注明其受限状态。这在源生产流程中确实发生过:一个只有内部员工才能看到的功能应评审者要求被展示,并做了相应标记。
4. 修复不成立的部分
- 重写 部分真实的句子,使其成为来源支持的最强版本。保留作者想要表达的意思;将机制改为真实的机制。
- 删除 没有来源的内容。不要将其模糊化;模糊的声明仍然是声明。
- 绝不让标签漂移。 一个标记为“示例性”的设计素材,在后续美观修改时不能丢失该标签,除非重新检查无标签版本所做出的声明。
- 定位优先于文档。 如果一份演示文稿或 PRD 说了
never_say或 CLAIMS.md 禁止的内容,规则优先,句子必须更改。 - 仅使用当前名称。 使用
product.yaml names中的规范名称,即使实时 UI 或代码仍显示遗留字符串。用 grep 搜索lines.tsv、规格和模板中每一个遗留字符串和每条banned_terms条目(竞争对手、团队避免在屏幕上显示的第三方供应商、真实客户),并修复每个命中。
5. 当请求与产品冲突时
当简报或评审者要求代码不支持的东西时,不要构建假的,也不要默默放弃。提出一个包含选项和建议默认值的封闭式问题,每轮最多保留三个这样的问题,因为开放式的否决清单通常无人回应,而沉默会变成无人做出的决定。“只做真实的”模式:
简报显示 Acme Tasks 自己预订了会议室。但代码仅创建任务并链接房间的日历 (frontend/src/rooms/LinkRoom.tsx:22@1a2b3c4);实际预订发生在日历应用中。选哪个?
- 只做真实的(推荐): 显示链接步骤并说“链接房间的日历”。
- 将日历应用的预订屏幕作为设计素材展示(已标记),并叙述为日历的步骤。
- 放弃这个节拍。
将答案记录在 CLAIMS.md 中,并据此设置结论。
6. 编写 TRUTH.md
# 真相:<video>
锁定版本:前端 main@1a2b3c4,后端 main@5d6e7f8。检查日期:2026-01-12。
| id | 句子 | 来源 | 可见性 | 结论 | 备注 |
|---|---|---|---|---|---|
| N1 | Acme Tasks 根据你的日历计划你的一天。 | frontend/src/planner/plan.ts:31@1a2b3c4; https://docs.example.com/planner | ui | backed | |
| N2 | 过期任务在午夜移到明天。 | backend/jobs/rollover.py:12-30@5d6e7f8 | backend | backed | 不在屏幕上显示 |
| screen:board | 包含三个任务的面板,其中一个过期 | frontend/src/pages/board/BoardPage.tsx:14@1a2b3c4 | ui | backed | |
| screen:call | 与客户的电话通话 | (设计素材) | mock | mock | 在 BRIEF 中标记 |
## 未解决问题
1. <带有推荐答案的封闭式问题>
每个 lines.tsv 的行 ID 对应一行,句子需要精确复制(检查时会比较它们,因此在真相验证通过后编辑一行会导致失败,直到重新验证)。每个画面对应一行,ID 为 screen:<name>,需与 SOURCES.md 匹配。多个引用放在一个单元格内,以分号分隔。
7. 检查它
PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/product-truth/scripts/truth_check.py" <video_dir>
检查会在以下情况失败:一个行没有对应的 TRUTH.md 行;句子已更改;叙述行的结论不是 backed 或 approved;引用的角色未锁定;引用的 SHA 与锁定的版本不一致(代码已移动,需重新验证);引用的文件不在导出中;或引用的行号超出文件末尾。修复每个失败;不要编辑检查脚本。
向用户报告:多少行和画面已背书,你重写和删除了哪些(带原因),哪些在等待批准,以及未解决的问题。