maintain-verification-skill

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Maintain a verification skill

维护验证 skill

A feature map rots the moment the app changes. This skill is the upkeep loop for a skill generated by
/create-verification-skill
(or any project-local verification skill with a feature map). The unit of rigor is the feature, not every sentence: cover every feature file from source and exercise every feature live, without terminalising every bullet.
feature map 会在 app 发生变化的那一刻开始失真。此 skill 是维护由
/create-verification-skill
生成的 skill(或任何带有 feature map 的项目本地验证 skill)所用的维护循环。严谨性的衡量单位是 feature,而不是每一句话:从源码覆盖每个 feature 文件,并实时演练每个 feature,但不必把每个条目都转化为终端命令。

Outcomes

结果

Pick one, and say which:
  • clean — every feature got source and live coverage; nothing worth shipping. No branch, no PR.
  • changed — one PR ships proven doc, harness, or map corrections.
  • blocked — coverage could not finish or a proven fix could not ship safely. Say exactly what blocked it.
选择一项,并明确说明是哪一项:
  • clean — 每个 feature 都获得了源码和实时运行覆盖;没有值得提交的内容。不创建 branch,也不创建 PR。
  • changed — 通过一个 PR 提交经过验证的文档、harness 或 map 修正。
  • blocked — 覆盖未能完成,或经过验证的修正无法安全提交。准确说明具体的阻塞原因。

Edit scope

编辑范围

Only edit the verification skill's own directory (its SKILL.md, features/, and any harness scripts it owns). Never edit product code during a run: a behavior the map describes that the app no longer does is either doc drift (fix the map) or a product regression (report it, don't paper over it in docs).
只能编辑验证 skill 自己的目录(其
SKILL.md
、
features/
,以及它所拥有的任何 harness 脚本)。运行期间绝不编辑产品代码:feature map 所描述但 app 已不再具备的行为,要么属于文档漂移(修正 map),要么属于产品回归(报告问题,不要用文档掩盖)。

Pass

执行流程

  1. Locate the target. Find the verification skill to maintain: the project-local skill whose body has launch/drive sections and a feature map (usually
    .cursor/skills/verify-*/
    ). Several candidates → ask which one; none → stop and point at
    /create-verification-skill
    instead of inventing a target.
  2. Index hygiene. Read the feature map README and glob its sibling files. Fix missing, extra, duplicate, or dead entries. Lightweight; no generated inventory.
  3. Source wave. One read-only subagent per feature file, launched concurrently. Each explains "how does this user-facing feature work?" from source, flags likely doc drift with citations, and returns one concise live-verification recipe. Children never drive the app and never edit files. Return shape: feature summary / source entry points / likely drift or none / one recipe.
  4. Reconcile. Every feature file has a returned summary. Merge overlapping recipes into as few app states as practical. Spot-check cited drift; don't re-prove clean claims. Sweep recent churn for user-facing surfaces missing from the map — require a concrete source path before calling one missing.
  5. Live pass. Required even when source looks clean. The coordinator owns all driving; follow the verification skill's own launch model — one long-lived instance driven serially for servers and UIs, or a fresh isolated session per drive for short-lived CLIs (the skill's Launch section decides, not this one). Exercise every feature at least once, and hold three invariants the whole pass, whatever the failure: (1) never drive an instance you haven't health-checked since it last did something surprising — doctor before first drive, doctor on each fresh session where sessions are the unit, doctor again after any failed drive, and where doctor can't see the failure (a wedged UI state on a healthy process), reset to a known state or relaunch rather than hoping; (2) evidence captured so far survives every cleanup, checked at its named location, not assumed; (3) nothing a drive started outlives that drive's usefulness — failed-iteration residue is cleaned whether the session is stuck, exited, or shared (for a shared instance, clean the residue, not the instance). A doctor failure caused by skill drift is drift: fix it under edit scope and retry once — restart whatever the fix invalidated, nothing more — before calling the pass
    blocked
    . A feature that can't be reached is
    verified-unreachable
    only with the concrete prerequisite (auth, entitlement, OS, external state) and the route attempted; if the map omits that prerequisite, that's drift. Any harness fix from triage gets re-driven live before it ships. Final teardown happens after the last drive of the run — including those re-proofs — so nothing outlives the run (evidence stays, per the skill).
  6. Triage. Wrong or missing user-POV description → doc drift, fix it. Working behavior the harness can't drive → harness gap, fix it; a harness fix follows the same helpers rule as generation (scripts executable, invocation documented in the skill body). App behavior that's actually broken → product gap; record it for the user, keep it out of this PR.
  7. Ship or stop. For changed: one PR of proven corrections, re-read every changed file first. For clean or blocked: no PR, report the outcome and the coverage honestly.
Keep concise run notes (features covered, unreachable prerequisites, confirmed drift, outcome) in a scratch location; don't commit them.
  1. 定位目标。 找到要维护的验证 skill:正文中包含 launch/drive 章节和 feature map 的项目本地 skill(通常位于
    .cursor/skills/verify-*/
    )。如果存在多个候选目标,询问用户选择哪一个;如果不存在,则停止并指向
    /create-verification-skill
    ,不要自行虚构目标。
  2. 索引整理。 阅读 feature map 的 README,并使用 glob 匹配其同级文件。修复缺失、多余、重复或失效的条目。保持轻量;不要生成额外的 inventory。
  3. 源码读取阶段。 针对每个 feature 文件启动一个只读 subagent,并发执行。每个 subagent 根据源码说明“这个面向用户的 feature 是如何工作的?”,标记可能存在的文档漂移并提供引用,然后返回一份简洁的实时验证方案。子 Agent 绝不驱动 app,也绝不编辑文件。返回格式:feature 摘要 / 源码入口点 / 可能存在的漂移或无漂移 / 一份验证方案。
  4. 汇总校准。 每个 feature 文件都应有一份返回的摘要。将相互重叠的验证方案合并为尽可能少的 app 状态。对引用的漂移进行抽查;不要重复证明已经判定为正常的结论。检查近期变更,找出 map 中缺失的用户可见功能面;在判定某项缺失之前,必须找到具体的源码路径。
  5. 实时验证。 即使源码看起来没有问题,也必须执行。协调器负责所有驱动操作;遵循验证 skill 自身的 Launch 模型——对于 server 和 UI,使用一个长生命周期的 instance 并串行驱动;对于短生命周期的 CLI,每次 drive 使用一个全新的隔离 session(具体方式由该 skill 的 Launch 章节决定,而不是由本流程决定)。每个 feature 至少演练一次,并且无论发生什么失败,整个流程都必须始终遵守以下三项不变量:(1) 绝不能驱动一个自上次出现异常行为后尚未通过健康检查的 instance——首次 drive 前执行 doctor;以 session 为单位时,每个全新 session 都要执行 doctor;任何 drive 失败后再次执行 doctor;如果 doctor 无法发现失败(进程健康,但 UI 状态卡死),则重置到已知状态或重新启动,而不是碰运气;(2) 迄今捕获的 evidence 必须在每次 cleanup 后继续可用,并应在其指定位置实际检查,而不是想当然地认为它仍然存在;(3) 一次 drive 启动的任何进程或资源都不得在该 drive 不再有用后继续运行——无论 session 卡住、退出还是共享,都必须清理失败迭代留下的残留(对于共享 instance,只清理残留,不清理 instance 本身)。如果 doctor 失败是由 skill 漂移引起的,这也属于漂移:在编辑范围内修正后重试一次——只重新启动被该修正影响的对象,不做其他操作——然后才能将流程判定为
    blocked
    。只有在明确给出具体前置条件(auth、entitlement、OS 或外部状态)以及已尝试的路径后,无法访问的 feature 才能标记为
    verified-unreachable
    ;如果 map 遗漏了该前置条件,这同样属于漂移。triage 中产生的任何 harness 修正,在提交前都必须重新进行实时驱动验证。运行中的最后一次 drive(包括所有重新验证)完成后,才能执行最终 teardown,确保没有任何内容比本次运行存续更久(evidence 按 skill 的要求保留)。
  6. 分类处理。 错误或缺失的 user-POV 描述 → 文档漂移,修正它。harness 无法驱动但实际正常工作的行为 → harness 缺口,修正它;harness 修正遵循生成时相同的 helpers 规则(脚本必须可执行,调用方式必须记录在 skill 正文中)。app 行为确实损坏 → 产品缺口;为用户记录该问题,但不要将其纳入本 PR。
  7. 提交或停止。 对于 changed:用一个 PR 提交经过验证的修正,并先重新阅读每个已修改文件。对于 clean 或 blocked:不创建 PR,诚实报告结果和覆盖情况。
在临时位置保留简洁的运行记录(已覆盖的 feature、无法访问所需的前置条件、确认的漂移、结果);不要提交这些记录。