Maintain a verification skill
A feature map rots the moment the app changes. This skill is the upkeep loop for a skill generated by /skill: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.
Outcomes
Pick one, and say which:
- clean. Every feature got source and live coverage. Nothing is worth shipping, so create no branch or 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 (fix the map) or a product regression (report it, don't paper over it in docs).
Pass
Locate the target. Find the verification skill to maintain: the project-local skill whose body has launch/drive sections and a feature map (usually .pi/skills/verify-*/). Several candidates → ask which one; none → stop and point at /skill:create-verification-skill instead of inventing a target.
Index hygiene. Read the feature map README and glob its sibling files. Fix missing, extra, duplicate, or dead entries. Lightweight; no generated inventory.
Source wave. Follow ../../docs/delegation.md. Launch one read-only delegate per feature file together. Each explains "how does this user-facing feature work?" from source, flags likely doc drift with citations, and returns one concise live-verification recipe. Delegates never drive the app or edit files. Return shape: feature summary / source entry points / likely drift or none / one recipe.
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.
Live pass. 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 use a fresh isolated session per drive for short-lived CLIs. The skill's Launch section decides which model applies. Exercise every feature at least once and hold three invariants throughout the pass, whatever the failure.
First, never drive an instance you haven't health-checked since it last did something surprising. Run doctor before the first drive, on each fresh session when sessions are the unit, and after any failed drive. When doctor can't see the failure, such as a wedged UI state on a healthy process, reset to a known state or relaunch rather than hoping.
Second, preserve all evidence captured so far through every cleanup. Check it at its named location instead of assuming it survived.
Third, clean anything a drive started once it is no longer useful. Clean failed-iteration residue whether the session is stuck, exited, or shared. For a shared instance, clean the residue rather than the instance.
A doctor failure caused by skill drift is drift. Fix it under edit scope and retry once. Restart only what the fix invalidated. If the retry fails, call the pass blocked.
A feature is verified-unreachable only when you record the concrete prerequisite and the route attempted. Concrete prerequisites include auth, entitlement, OS, or external state. If the map omits that prerequisite, that's drift. Re-drive any harness fix from triage live before it ships.
Perform final teardown after the last drive of the run, including all re-proofs, so nothing outlives the run. Evidence stays as the skill requires.
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.
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---2name: maintain-verification-skill3description: Periodic pass that keeps a project's verification skill and feature map honest: parallel source readers per feature, one live session driving every feature, at most one PR of proven corrections. Use for /skill:maintain-verification-skill or "audit the verify skill".4---56# Maintain a verification skill78A feature map rots the moment the app changes. This skill is the upkeep loop for a skill generated by `/skill: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.910## Outcomes1112Pick one, and say which:1314- **clean.** Every feature got source and live coverage. Nothing is worth shipping, so create no branch or PR.15- **changed.** One PR ships proven doc, harness, or map corrections.16- **blocked.** Coverage could not finish or a proven fix could not ship safely. Say exactly what blocked it.1718## Edit scope1920Only 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).2122## Pass23240. **Locate the target.** Find the verification skill to maintain: the project-local skill whose body has launch/drive sections and a feature map (usually `.pi/skills/verify-*/`). Several candidates → ask which one; none → stop and point at `/skill:create-verification-skill` instead of inventing a target.25261. **Index hygiene.** Read the feature map README and glob its sibling files. Fix missing, extra, duplicate, or dead entries. Lightweight; no generated inventory.27282. **Source wave.** Follow [`../../docs/delegation.md`](../../docs/delegation.md). Launch one read-only delegate per feature file together. Each explains "how does this user-facing feature work?" from source, flags likely doc drift with citations, and returns one concise live-verification recipe. Delegates never drive the app or edit files. Return shape: feature summary / source entry points / likely drift or none / one recipe.29303. **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.31324. **Live pass.** 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 use a fresh isolated session per drive for short-lived CLIs. The skill's Launch section decides which model applies. Exercise every feature at least once and hold three invariants throughout the pass, whatever the failure.33 First, never drive an instance you haven't health-checked since it last did something surprising. Run doctor before the first drive, on each fresh session when sessions are the unit, and after any failed drive. When doctor can't see the failure, such as a wedged UI state on a healthy process, reset to a known state or relaunch rather than hoping.34 Second, preserve all evidence captured so far through every cleanup. Check it at its named location instead of assuming it survived.35 Third, clean anything a drive started once it is no longer useful. Clean failed-iteration residue whether the session is stuck, exited, or shared. For a shared instance, clean the residue rather than the instance.36 A doctor failure caused by skill drift is drift. Fix it under edit scope and retry once. Restart only what the fix invalidated. If the retry fails, call the pass `blocked`.37 A feature is `verified-unreachable` only when you record the concrete prerequisite and the route attempted. Concrete prerequisites include auth, entitlement, OS, or external state. If the map omits that prerequisite, that's drift. Re-drive any harness fix from triage live before it ships.38 Perform final teardown after the last drive of the run, including all re-proofs, so nothing outlives the run. Evidence stays as the skill requires.39405. **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.41426. **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.4344Keep concise run notes (features covered, unreachable prerequisites, confirmed drift, outcome) in a scratch location; don't commit them.
shishiv