/video-new
在开始构建任何内容之前,先写下视频必须解释的内容以及可以声明的信息,并让审核人员签署这两项。然后停止。
为什么存在这个技能:在开发这些技能的生产环境中,有9次版本迭代(共26次)是因为视频没有解释审核人员关心的某个功能。没有人预先记录这些功能,因此每个功能都在审核中才暴露出来,导致一次完整的渲染和 QA 周期,然后还必须手动应用到每一个其他视频上。定位和声明同样导致了另外3次版本迭代。预先签署的两份文档比这些轮次中的任何一次都要便宜。
开始之前
PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
找到产品:当前目录上方最近的包含 product.yaml 的文件夹。如果没有,告知用户先运行 /product-new(你不能代劳运行:它是由用户调用的)。读取 product.yaml、kit/RULES.md 以及 videos/ 中任何同级视频的 BRIEF:同级视频的覆盖矩阵和声明清单是最佳的起始点,并且不同视频之间的演员表必须保持一致。
视频 ID 来自参数(小写、数字、短横线)。如果 videos/<video>/ 已存在,则停止:现有视频应通过 /video-review 推进,绝不要重新开始。
1. 询问视频用途
一条消息,最多四个问题,每个都附带建议的默认值:
- 谁观看以及在哪里发布(宣传片、简短产品演示、文档页面、新手引导、落地页循环)。
- 观看者之后必须相信或能够做什么(一句话)。
- 大致时长(默认值:宣传片 90 秒,演示 30 秒,文档 120 秒,教程 240 秒,循环 15 秒)。演示是宣传片的精简版,只聚焦一到两个功能:相同的开场、结束画面和结尾徽标,更少的章节。当审核人员说“快速演示”或要求时长低于 45 秒时选择它。
- 审核人员认为哪些功能最重要。要求按名称提供,并询问其中哪些必须演示工作状态而不仅仅是提及。
2. 创建文件夹
"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/video-new/scripts/new_video.py" <product_dir> <video> \
--format <format> [--title "<title>"] [--duration <s>]
它会复制 _template/video,填充 BRIEF 的 frontmatter(标题、视频、格式、时长、语言和来自 product.yaml 的审核人员,版本 1)并将两个签名都留空。它会拒绝重复的 ID。
3. 编写三份文档
在编写之前,请阅读 references/sheets.md 以了解每份文档的格式和已完成的示例行。
- BRIEF.md:意图(引用用户自己的话)、受众、建议的章节、备注(包含视频将使用的所有虚构姓名和数字,来自产品演员表,未经询问不得新建),以及一个空的 v1 变更日志条目。
- COVERAGE.md:每个功能一行,包含“必须在屏幕上解释?是/否”、解释该功能的章节以及证明(观看者看到的内容)。一个仅在结束画面上命名的功能未被覆盖:这正是导致最多版本迭代的差距。包括可配置的部分(设置、触发器(包括计划的)、转接、后续操作),因为这些正是审核人员在事后反复要求的功能。
- CLAIMS.md:定位行(来自
product.yaml,绝不要来自营销文档)、要避免的短语(never_say加上用户添加的任何内容)、每个需要批准的叙述声明、批准的口号,以及标准产品名称与其旧版字符串的对照。
对照你在 sources/ 和文档中看到的内容检查每个声明和功能。如果产品没有实现用户要求的功能,请用一个封闭式问题和推荐选项来说明(“仅展示已存在的”通常是正确的默认选项)。不要将无法通过代码验证的功能写入矩阵。
4. 提议章节
将章节表格添加到 BRIEF.md 中。每个章节一个想法,每个章节一个框架,每个“必须解释”的功能都映射到一个章节。以上下文开场(产品名称和一行说明它是什么),绝不要直接从 UI 中间开始。默认情况下以 1 倍缩放显示整个页面;深度缩放曾两次在原始制作中被否决。以广度(产品还能做什么)结束,然后是结尾徽标。
5. 停止并请求签名
向用户展示以下内容,一条消息内包含:
- 覆盖矩阵(“是”行)和章节表格。
- 定位行、需要批准的声明和建议的口号。
- 最多三个封闭式决策,每个附带默认值(例如口号、演员表名称、省略某个功能)。说明沉默的含义:即接受默认值。
然后请审核人员签署。审核人员要么亲自将其姓名写入 BRIEF.md 中的 coverage_signed_by 和 claims_signed_by,要么以其自己的方式告知你以其名义签署,然后你运行:
"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/video-new/scripts/sign.py" <video_dir> \
--coverage "<reviewer name>" --claims "<reviewer name>"
绝不要主动签署,绝不要因为文档“看起来完整”就签署,绝不要使用审核人员未提供的姓名签署。签名是审核人员对矩阵将作为其评判视频标准的声明。sign.py 拒绝处理空的矩阵或缺少定位行的情况;不带任何标志时,它只显示状态。
即使在同一消息中用户签署了,也不要在此处构建、渲染、录制旁白或派遣子代理。构建由 /video-build 负责,由用户输入。这个分离能防止代理在未签署的 BRIEF 上启动昂贵的构建。
报告
| 项目 | 值 |
|---|---|
| 视频 | videos/<video>/,格式,目标时长 |
| 覆盖 | 需要在屏幕上解释的 N 个功能,仅列出的 M 个,章节 |
| 声明 | 定位,等待批准的声明 |
| 决策 | 最多三个封闭式问题及其默认值 |
| 签名 | 未签署(或由谁签署) |
下一步,签署后:/video-build <video>。