maintain-verification-skill

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Maintain a verification skill

维护Verification 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)会在应用变更的瞬间开始失效。本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均已完成源文件覆盖和实时覆盖;无值得交付的内容。无需创建分支或PR。
  • changed — 提交一个PR,交付经过验证的文档、测试工具(harness)或地图修正。
  • 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).
仅可编辑Verification Skill自身的目录(其SKILL.md、features/目录以及它所拥有的任何harness脚本)。运行过程中绝不可编辑产品代码:如果地图描述的行为应用已不再具备,要么是文档漂移(doc drift)(修复地图),要么是产品回归(product regression)(上报问题,不要在文档中掩盖)。

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. 定位目标:找到需要维护的Verification Skill:项目本地的Skill,其主体包含启动/驱动部分和feature map(通常位于
    .cursor/skills/verify-*/
    目录下)。若有多个候选→询问选择哪一个;若没有→停止操作,转而指向
    /create-verification-skill
    ,不要自行创建目标。
  2. 索引检查:阅读feature map的README并匹配其同级文件。修复缺失、多余、重复或无效的条目。操作需轻量化;无需生成清单。
  3. 源文件扫描:为每个feature文件启动一个只读的子Agent(subagent),并行运行。每个子Agent从源文件解释“这个面向用户的feature是如何工作的?”,标记可能存在的文档漂移并附上引用,返回一个简洁的实时验证方案。子Agent绝不能驱动应用,也不能编辑文件。返回格式:feature摘要 / 源文件入口点 / 可能存在的漂移或无漂移 / 一个验证方案。
  4. 核对:每个feature文件都有返回的摘要。将重叠的方案合并为尽可能少的应用状态。抽查引用的漂移情况;无需重新验证无问题的内容。检查近期变更,寻找feature map中遗漏的面向用户的界面——在判定遗漏前,需提供具体的源文件路径。
  5. 实时检查:即使源文件看起来无问题,此步骤也必不可少。协调器负责所有驱动操作;遵循Verification Skill自身的启动模型——对于服务器和UI,使用一个长期运行的实例进行串行驱动;对于短期运行的CLI,每次驱动使用一个全新的独立会话(由Skill的Launch部分决定,而非本流程)。至少演练每个feature一次,整个检查过程中需保持三个不变量,无论是否失败:(1) 绝不能驱动一个自上次出现异常后未进行健康检查的实例——首次驱动前检查健康状态,在以会话为单位的每个新会话中检查,任何驱动失败后再次检查;如果健康检查无法发现故障(如健康进程上的UI状态卡死),则重置为已知状态或重新启动,而非抱有侥幸;(2) 到目前为止捕获的证据在每次清理后都能保存在指定位置,不可假设其存在;(3) 驱动启动的任何内容都不能超过该驱动的有用期限——无论会话是卡死、退出还是共享(对于共享实例,清理残留内容,而非实例本身),失败迭代的残留都需清理。若因Skill漂移导致健康检查失败,则属于漂移:在编辑范围内修复后重试一次——重启修复操作失效的内容,仅此而已——之后再判定检查流程为
    blocked
    。若某个feature无法访问,只有在提供具体的前置条件(权限、授权、操作系统、外部状态)和尝试的路径后,才能标记为
    verified-unreachable
    ;如果地图遗漏了该前置条件,则属于漂移。任何来自问题排查的harness修复,在交付前都需重新进行实时驱动。最终清理在本次运行的最后一次驱动(包括那些重新验证的操作)之后进行,确保没有内容在运行结束后残留(根据Skill要求,证据保留)。
  6. 问题排查:错误或缺失的用户视角描述→文档漂移,修复它。harness无法驱动的正常行为→harness存在缺口,修复它;harness修复需遵循与生成相同的辅助规则(脚本可执行,调用方式在Skill主体中记录)。应用实际存在的行为故障→产品缺口;记录下来告知用户,不要纳入本次PR。
  7. 交付或停止:对于changed结果:提交一个包含经过验证的修正的PR,先重新阅读所有变更文件。对于clean或blocked结果:无需提交PR,如实报告结果和覆盖情况。
在临时位置保存简洁的运行记录(覆盖的feature、无法访问的前置条件、已确认的漂移、结果);不要提交这些记录。