maintain-verification-skill

name	maintain-verification-skill
description	Keep a project's verification skill and feature map honest through parallel source review and a live pass over every feature. Use for /maintain-verification-skill, periodic verification upkeep, or requests to audit, refresh, or repair a repo's verify skill.

Maintain a verification skill

A feature map rots as the app changes. This is the upkeep loop for a skill generated by verifier-setup or any project-local verification skill. The unit of rigor is the feature: cover every feature file from source and exercise every reachable feature live.

Outcomes

Pick one, and say which:

• clean — every feature received source and live coverage; nothing needs changing.
• changed — proven documentation, harness, or map corrections are ready.
• blocked — coverage could not finish or a correction could not be proven 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

0. Locate the target. Find the project-local verification skill whose body has launch and drive instructions. Check .agents/skills/, .claude/skills/, .cursor/skills/, and the repo's documented skill location. Several candidates means ask which one. None means stop and point at verifier-setup.

   If the target lacks a feature map, seed features/README.md plus 3-5 files for the primary user-facing routes, commands, menus, or documented flows. Keep the map inside the verification skill directory, then continue.

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

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

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

4. Live pass. Required even when source looks clean. Explicit invocation authorizes following the target skill's documented launch and teardown flow; otherwise stop before starting a server. Read the nearest README first. Use one long-lived instance driven serially for servers and UIs, or a fresh isolated session per drive for short-lived CLIs.

   Exercise every feature at least once. Doctor before the first drive, on each fresh session, and after any failed drive. Reset or relaunch wedged state instead of hoping. Preserve captured evidence across cleanup. Clean only processes and scratch state started by this run; never kill by broad process name. A doctor failure caused by skill drift is drift: fix it within edit scope and retry once. Mark an unreachable feature verified-unreachable only with the concrete prerequisite and attempted route. Re-drive every harness correction before accepting it. Tear down what this run started after the last drive while retaining evidence.

5. Triage. Wrong or missing user-point-of-view description means doc drift; fix it. Working behavior the harness cannot drive means a harness gap; fix it and document executable helpers. Broken app behavior means a product gap; report it and do not edit product code during this run.

6. Hand off. For changed, re-read every changed file and report the proven correction set. Commit, push, or open a PR only when the user requested that delivery workflow. For clean or blocked, report the outcome and coverage honestly.

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