Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

maintain-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 的项目本地 verification skill）的保养环。严谨单位是功能，不是每句话：从源码覆盖每个功能文件，并 live 走每个功能，但不把每条子弹都终端化。

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 — 每个功能都有源码与 live 覆盖；没什么值得交付。无分支、无 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).

只编辑 verification skill 自己的目录（其 SKILL.md、features/、以及它拥有的 harness 脚本）。一次跑里绝不改产品代码：map 描述的行为应用已不做，要么是文档漂移（修 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. 定位目标。 找到要维护的 verification skill：正文有 launch/drive 小节和 feature map 的项目本地 skill（通常 .cursor/skills/verify-*/）。多个候选 → 问哪个；没有 → 停下并指向 /create-verification-skill，别发明目标。

  3. Index hygiene. Read the feature map README and glob its sibling files. Fix missing, extra, duplicate, or dead entries. Lightweight; no generated inventory.

  4. 索引卫生。 读 feature map README，glob 其兄弟文件。修缺失、多余、重复或死条目。轻量；不生成清单。

  5. 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.

  6. 源码波。 每个功能文件一个只读 subagent，并发启动。各自从源码解释「这面向用户功能怎么工作」、用引用标出可能文档漂移，并返回一份简洁 live 验证配方。子 agent 绝不驱动应用、绝不改文件。返回形状：功能摘要 / 源码入口 / 可能漂移或无 / 一份配方。

  7. 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.

  8. 和解。 每个功能文件都有返回摘要。把重叠配方合并成尽量少的应用状态。抽查引用的漂移；干净主张别再证。扫近期 churn，找 map 漏掉的面向用户面——点名缺失前要有具体源码路径。

  9. 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).

  10. Live 巡检。 即使源码看起来干净也必做。协调者拥有全部驱动；跟 verification skill 自己的 launch 模型——服务器和 UI 用一个长寿实例串行驱动，短命 CLI 每次 drive 新隔离会话（由该 skill 的 Launch 小节决定，不是本 skill）。至少走一遍每个功能，整次巡检无论失败都守三条不变量：(1) 实例上次做出意外事后，未健康检查就别再驱动——首次 drive 前 doctor，以会话为单位时每个新会话 doctor，失败 drive 后再 doctor；doctor 看不见失败时（健康进程上卡住的 UI），重置到已知状态或重启，别指望好运；(2) 已抓证据在每次 cleanup 后仍在，到点名位置核对，不假设；(3) drive 启动的东西不比该 drive 有用期活得更久——失败迭代残留无论会话卡住、已退出还是共享都要清（共享实例清残留，不清实例）。因 skill 漂移导致的 doctor 失败就是漂移：在编辑范围内修并重试一次——只重启修复使失效的东西——再宣布巡检 blocked。到不了的功能只有带着具体前置（认证、权益、OS、外部状态）和尝试过的路由才算 verified-unreachable；map 漏了该前置就是漂移。分诊出的任何 harness 修复交付前要再 live 驱动。最终 teardown 在本跑最后一次 drive（含那些再证明）之后，让没有东西比本跑活得久（证据按 skill 留下）。

  11. 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.

  12. 分诊。 用户视角描述错或缺 → 文档漂移，修它。行为正常但 harness 开不了 → harness 缺口，修它；harness 修复跟生成时同样的 helpers 规则（脚本可执行、调用写在 skill 正文）。应用行为真坏了 → 产品缺口；记给用户，别进本 PR。

  13. 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.

  14. 交付或停下。 changed：一个已证明修正的 PR，先重读每个改过的文件。clean 或 blocked：无 PR，诚实报告结果与覆盖。

Keep concise run notes (features covered, unreachable prerequisites, confirmed drift, outcome) in a scratch location; don’t commit them.

简洁跑次笔记（覆盖的功能、不可达前置、确认的漂移、结果）放临时位置；别 commit。