--- name: maintain-verification-skill description: "一轮定期维护,让项目的验证 skill 和功能地图保持诚实:每个功能一个并行的源码读者,一次现场会话驱动每一个功能,最多一个 PR 交已证明的修正。用于 /maintain-verification-skill 或「audit the verify skill」。" disable-model-invocation: true --- # 维护验证 skill 应用一变,功能地图就开始烂。这个 skill 是维护循环,对象是 `/create-verification-skill` 生成的 skill(或任何带功能地图的项目本地验证 skill)。严谨的单位是功能,不是每一句:从源码覆盖每一个功能文件,并现场操练每一个功能,不必把每一条都跑成终态。 ## 结果 选一个,并说明是哪一个: - **干净**:每个功能都有源码覆盖和现场覆盖。没有值得交出去的东西。不开分支,不开 PR。 - **已改**:一个 PR 交已证明的文档、harness 或地图修正。 - **堵住**:覆盖没能做完,或一个已证明的修复不能安全地交出去。准确说明堵住了什么。 ## 编辑范围 只编辑验证 skill 自己的目录(它的 SKILL.md、features/,以及它拥有的任何 harness 脚本)。一次运行期间绝不编辑产品代码:地图描述的行为应用已经不再做,要么是文档漂移(修地图),要么是产品回退(报告它,不要在文档里把它糊过去)。 ## 一轮 0. **定位目标。** 找到要维护的验证 skill:正文里有启动和驱动两节、并且有功能地图的那份项目本地 skill(通常是 `.cursor/skills/verify-*/`)。有多个候选就问是哪一个。一个都没有就停下,指向 `/create-verification-skill`,不要发明一个目标。 1. **索引整理。** 读功能地图的 README,并 glob 它的同级文件。修掉缺失、多余、重复或死掉的条目。轻量。不要生成清单。 2. **源码一轮。** 每个功能文件一个只读 subagent,并发拉起。每个从源码解释「这个面向用户的功能是怎么工作的?」,用引用标出可能的文档漂移,并返回一份简短的现场验证配方。子级绝不驱动应用,也绝不编辑文件。返回形状:功能摘要 / 源码入口 / 可能的漂移或没有 / 一份配方。 3. **对账。** 每个功能文件都有一份返回的摘要。把重叠的配方合并成尽可能少的应用状态。抽查被引用的漂移。已经干净的声称不要再证明一遍。扫一遍最近的变动,找地图里缺的用户可见表面。称某个为缺失之前,要有一条具体的源码路径。 4. **现场一轮。** 即使源码看起来干净也必须做。所有驱动由协调者拥有。遵循验证 skill 自己的启动模型:服务器和 UI 用一个长寿命实例串行驱动,短命 CLI 则每次驱动一个新的隔离会话(由 skill 的启动一节决定,不是由这一份决定)。每个功能至少操练一次,并且整轮守住三条不变量,无论失败与否:(1)绝不驱动一个实例,如果自从它上次做出意外的事之后,你还没给它做健康检查。第一次驱动前做诊断,以会话为单位时每个新会话做诊断,任何失败的驱动之后再做诊断。诊断看不到失败时(进程健康,但 UI 状态卡住),重置到已知状态或重新启动,不要指望它自己好。(2)到目前为止抓到的证据挺过每一次清理。在它被点名的位置检查,不要假定。(3)一次驱动启动的东西,不得活过这次驱动的用处。失败迭代的残留要清掉,无论会话是卡住、已退出,还是共享的。共享实例只清残留,不清实例。诊断失败如果是 skill 漂移引起的,那就是漂移:在编辑范围内修,并重试一次。修复作废了什么,就重启什么,不要多做。然后才把这一轮叫成 `blocked`。一个到不了的功能,只有带上具体前提(认证、授权、操作系统、外部状态)和尝试过的路线,才是 `verified-unreachable`。地图漏了那个前提时,那就是漂移。分诊里来的任何 harness 修复,交出去之前都要再现场驱动一遍。最终拆除发生在这次运行的最后一次驱动之后,包括那些再证明,这样没有东西活过这次运行(证据留下,按 skill 所说)。 5. **分诊。** 用户视角的描述错了或缺了,是文档漂移,修它。行为是好的、harness 驱动不了,是 harness 缺口,修它。harness 修复遵循和生成时一样的辅助规则(脚本可执行,调用方式写在 skill 正文里)。应用行为确实坏了,是产品缺口。记下来给用户,不要放进这个 PR。 6. **交出或停下。** 已改:一个 PR 交已证明的修正,先重读每一个改过的文件。干净或堵住:不开 PR,诚实报告结果和覆盖。 把简短的运行笔记(覆盖了的功能、到不了的前提、确认了的漂移、结果)放在一个临时位置。不要 commit 它们。