maintain-verification-skill

Files (1)

• SKILL.md

SKILL.md (first lines)

<!-- Adapted from cursor/plugins pstack/maintain-verification-skill at ecc249f1e306fc64ddf83c7bed16cacf7c2239db (MIT). -->
<!-- Proof adapted from t3dotgg/tstack full-send at 1085050f3baed1ac724caa4a8166145fb2ac88af (MIT). -->

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

## Proof

The bar for every proof an agent claims, an upkeep run's or any other.

- **Proof** is evidence you observed yourself in this session: command output, a reproduction, a screenshot. Green mocked tests do not prove that the user experience works.
- **The ladder.** Use the most direct proof the change allows: reproduce the failure, fix it, then watch the same reproduction pass; run the project-declared checks for this stage (read Feature proof and gate placement in `dydo/guides/testing-strategy.md` from the repository root); add one focused test that fails without the fix when the behaviour has none; for UI or runtime behaviour, drive the app and look.
- **Proof recipe.** The crew member who did the work hands it up in its return's `proof:`: the exact commands or steps it ran and the evidence each showed, exact enough to rerun unchanged.
- **Cannot prove it** means not confident: say so on the record instead of claiming proof.

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

## Edit scope

Edit only the verification skill's own directory (its `SKILL.md`, `resources/features/`) and the control CLI it drives. Product code stays untouched during a run: a behaviour the map describes that the app no longer does is either doc drift (fix the map) or a product regression (report it to the user as a Bug, keep the map describing intended behaviour).

## Verification gaps from an inquisition

An inquisition's Drive phase files a *verification gap*, severity should, wherever a user can do
something the verification skill cannot. Its ticket names the user action, the drive steps that
stopped, and the capability the skill lacks. Take the ticket as this skill's input: run the pass
with the gap's feature in it, triage the gap in step 5 as a harness gap, or as doc drift or a
product gap if that is what it proves to be, and say which on the ticket. A fixed gap is re-driven
live before it ships, like any harness fix.

## Pass

0. **Locate the target.** Find the verification skill to maintain: the project-local skill whose body has launch/drive sections and a feature map (usually `skills/engineering/verify-*/`). Several candidates → ask which one; none → 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 and nested area folders. Fix missing, extra, duplicate, or dead entries. Lightweight; no generated inventory.

2. **Source wave.** The captain, or the map holder on a landing audit, commissions one read-only subagent per feature file, launched concurrently. Crew loading this keeps its role: return any step that shows the user or dispatches agents to your captain. 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. 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. **Doctor before trust.** 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. 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 survives.** Evidence captured so far survives every cleanup, checked at its named location, not assumed.
   3. **Nothing outlives its drive.** 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).

5. **Triage.** Wrong or missing user-POV description → doc drift, fix it. Working behaviour 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 behaviour that's actually broken → product gap; record it for the user, keep it out of this PR.

6. **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 the scratch directory, uncommitted.

From bodnarbalazs/dydo, MIT.

More from bodnarbalazs/dydo