# Maintain Verification Skill

> Use when a project's verification skill or feature map may have drifted, or for /maintain-verification-skill or "audit the verify skill".

- Skill: `tommy-ca/maintain-verification-skill` (Agent Skill)
- Install (CLI): `npx get-skill add tommy-ca/maintain-verification-skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tommy-ca/maintain-verification-skill/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: tommy-ca (https://skillmd.com/u/tommy-ca)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/tommy-ca/maintain-verification-skill

---


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

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

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). Never edit `openspec/`. The map lives at skill-root `features/`, not under OpenSpec.

## Upkeep Principles: SOLID, KISS, DRY, YAGNI

During maintenance sweeps, enforce clean design standards:
- **Single Responsibility:** Treat each feature markdown file as the sole authority for its feature's proof recipe. Keep harness execution logic strictly inside the driver.
- **Open/Closed:** Accommodate application changes by extending the feature map files or adding new journey files without changing the driver's interface.
- **Liskov Substitution:** Ensure all project-local drivers remain drop-in compatible across harnesses with uniform verbs (`doctor`, `launch`, `drive`, `cleanup`, `all`).
- **Interface Segregation:** Keep feature recipes decoupled so individual regressions can be verified in isolation without triggering the full sweep.
- **KISS & DRY:** Remove duplicated driver steps and redundant environment assertions. Favor simple native assertions over complex helper hierarchies.
- **YAGNI:** Remove dead gotchas, obsolete workarounds, and speculative feature drafts that no longer correspond to real code paths.

## 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. Look in the harness skill locations: run `scripts/scaffold_verification_skill.py --list` to enumerate the `verify-*` skills under them, or read the harness-to-directory mapping from `skills_dir` in `skills/setup-pstack/profiles/<host>.json` (or root `profiles/<host>.json`, resolved via `scripts.setup_pstack.resolve_profiles_dir`, mirrored by `DEFAULT_SKILLS_DIRS` in `scripts/portability_schema.py`).
   Plugin doctor lives at `<harness-skills-dir>/verify-pstack/`. App skills stay `<harness-skills-dir>/verify-<app>/`. Do not ship `verify-pstack` under shared `skills/`. Do not name an app skill `verify-pstack`. 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 compare its ordered references with actual regular sibling markdown files. The README Full sweep order is the live-pass order. Accept numbered backtick filenames under Full sweep or ordered links under Features with Full sweep prose directing that order. Normalize `./core.md` to `core.md`. Fix missing, duplicate, outside-directory, or unlisted references; reject directories and symlinks as feature files. When both sections list files, require the same coverage and check duplicates within each section separately. Each feature uses exactly four H2s in order: `Sub-features`, `How to get to it (user POV)`, `Driving it with <harness>`, and `Gotchas`, with a named harness. Run `scripts/scaffold_verification_skill.py --audit` or `scripts/scaffold_verification_skill.py --check --target-dir <skill-dir>` for automated Tier 1 structural validation. It checks structure, section headers including `## Helpers`, and feature map references while leaving runtime proof unassessed. Keep it lightweight. Do not generate an 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. This is Tier 3 observed model-backed runtime proof per `docs/verification-test-tiers.md`. Walk `features/README.md` top to bottom. That is the Full sweep. Driving one convenient feature is not a pass. 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. Follow that skill's isolation rule. Refuse to double-drive a shared instance. If the skill isolates with `--run-id`, do not invent `--checkout`. Audit the driver as you drive: a driver that binds a fixed port, shares a fixed temp path between concurrent runs, reads uncontained ambient state without fixture isolation (`PSTACK_FIXTURE_HOME`), fails to prune transient worktrees via `git worktree prune`, fails open on corrupt package descriptors, sleeps instead of waiting for an observed readiness signal, or abandons a child it started is a harness finding. Fix it in the driver, not with a longer timeout. In this repository the worked example for the correct shape is `tests/fixtures/resource-isolation/`. Exercise every feature at least once, bounding every command to 60 seconds with strict timeout handling. Reduce verdicts using the strict failure-first lattice: FAIL > BLOCKED > UNTESTED > PASS. 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, tagged with `evidence_level: observed_live`, 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).

5. **Triage.** Wrong or missing user-POV description is doc drift. Fix it. Working behavior the harness can't drive is a harness gap. Fix it. A harness fix follows the same helpers rule as generation (driver script executable, invocation documented in the skill body under `## Helpers`, timeout bounded). When candidate scoring divergence from probe scope movement occurs, the failure must provide discoverable remediation commands (`python3 scripts/eval_blinded_pstack.py --record-dsh`) rather than requiring manual hash archaeology. App behavior that's actually broken is a product gap. Record it for the user, keep it out of this PR. A capture that only shows "look, it opens" is not proof. Require the skill's Proof bar.

6. **Ship or stop.** For changed: one PR of proven corrections, re-read every changed file first. Review the actual PR diff against both [Thermo Nuclear Review](https://github.com/cursor/plugins/tree/main/thermos/skills/thermo-nuclear-review) (new correctness/security/breakage/feature-gate risks) and [Thermo Nuclear Code Quality Review](https://github.com/cursor/plugins/tree/main/thermos/skills/thermo-nuclear-code-quality-review) (structural complexity, duplicated checks, hidden coupling), using the external skills if installed or their published rubrics without copying a second canonical skill. Inspect existing PR review discussion *after* your first independent audit. Record each finding with the changed path, reproduction/contract proof, severity and disposition. If an independent verifier has not actually checked the current patch, label that proof `UNTESTED`, never `PASS` or "swarm verified". For clean or blocked: no PR, report the outcome and the coverage honestly.

Report draft status, structural validation, and runtime coverage separately. Six discovery directories reflect the six declared host census, plus candidate directories declared in profiles, but do not prove Droid native runtime operations or treat candidate status as verified proof in `verify_portable.py doctor --host all`. A clean structural check or source wave cannot replace the required live Full sweep. Use fresh run and step evidence directories, preserve earlier captures, and record instance identity and source revision. Keep doctor, trigger, stable result, and side effects tied to each feature. Confirm the evidence survives cleanup. If live coverage cannot finish, report blocked with the exact gap rather than calling the map verified.

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

