maintain-verification-skill

Files (1)

• SKILL.md

SKILL.md (first lines)

# Maintain a 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 for 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.

## Outcomes

Pick one, and say which.

- **clean.** Every feature got source and live coverage, and nothing is 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.

## 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, in which case you fix the map, or a product regression, in which case you report it and leave the docs alone.

## Pass

0. **Locate the target.** Find the verification skill to maintain. It is the project-local skill whose body has launch and drive sections and a feature map, usually `.cursor/skills/verify-*/`. If several candidates exist, ask which one. If none exist, stop and point at `/create-verification-skill` instead of inventing a target.

1. **Index hygiene.** Read the feature map README and glob its sibling files. Fix missing, extra, duplicate, or dead entries. This step is lightweight. Do not generate an inventory.

2. **Source wave.** Launch one read-only subagent per feature file, all at once. Each explains how the user-facing feature works from source, flags likely doc drift with citations, and returns one concise live-verification recipe. Children never drive the app and never edit files. The return shape is a feature summary, source entry points, likely drift or none, and one recipe.

3. **Reconcile.** Every feature file has a returned summary. Merge overlapping recipes into as few app states as practical. Spot-check cited drift. Do not re-prove clean claims. Sweep recent churn for user-facing surfaces missing from the map. Require a concrete source path before calling one missing.

4. **Live pass.** This pass is required even when source looks clean. The coordinator owns all driving. Follow the verification skill's own launch model. Use 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. Exercise every feature at least once, and hold three invariants for the whole pass, whatever the failure.

   1. Never drive an instance you have not health-checked since it last did something surprising. Run doctor before the first drive, on each fresh session where sessions are the unit, and again after any failed drive. Where doctor cannot see the failure, such as a wedged UI on a healthy process, reset to a known state or relaunch.
   2. Evidence captured so far survives every cleanup. Check it at its named location.
   3. Nothing a drive started outlives that drive's usefulness. Clean failed-iteration residue whether the session is stuck, has exited, or is 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, and nothing more, before calling the pass `blocked`. A feature that cannot be reached is `verified-unreachable` only with the concrete prerequisite (auth, entitlement, OS, or external state) and the route attempted. If the map omits that prerequisite, the omission is 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.

5. **Triage.** A wrong or missing user-POV description is doc drift. Fix it. Working behavior the harness cannot drive is a harness gap. Fix it. A harness fix follows the same helpers rule as generation. Scripts are executable, and the skill body documents the invocation. A harness fix may change how a check finds an element, how it waits, or its fixture data. It never weakens, skips, or deletes an assertion to make a check pass. Change an assertion only when the expected behavior changed on purpose and a person accepts the change in review. A skipped check counts as a failing check. When the fixed check guards a known bug, run it on a revision that still has that bug, such as the commit before its fix. Confirm it fails for the intended reason. App behavior that is actually broken is a product gap. Record it for the user and keep it out of this PR.

6. **Ship or stop.** For `changed`, open one PR of proven corrections, and re-read every changed file first. For `clean` or `blocked`, open no PR. Report the outcome and the coverage honestly.

Keep concise run notes (features covered, unreachable prerequisites, confirmed drift, outcome) in a scratch location. Do not commit them.

From dotts-h/qstack, MIT.

More from dotts-h/qstack