openwong2kim / maintain-verification-skill

<!--
Adapted from pstack skills/maintain-verification-skill/SKILL.md
(https://github.com/cursor/plugins, MIT, Copyright (c) 2026 Lauren Tan) and its
Claude Code port in pstack-claude plugins/pstack/skills/maintain-verification-skill/SKILL.md
(https://github.com/anishekkamal/pstack-claude, MIT, Copyright (c) 2026 Lauren Tan,
Copyright (c) 2026 Michael Denyer). See THIRDPARTYNOTICES.md.
-->

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; in this repo that is .claude/skills/verify-wmux/ with its driver scripts/control-wmux.mjs. The unit of rigor is the feature, not every sentence: cover every feature file from source and exercise every feature live, without turning every bullet into a terminal command.

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 files: .claude/skills/verify-wmux/ (SKILL.md, references/features/), the driver scripts/control-wmux.mjs, its pure helpers scripts/lib/control-wmux-lib.mjs and their test scripts/__tests__/controlWmux.test.mjs. 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

1. Locate the target. Find the verification skill to maintain: the project-local skill whose body has Launch/Doctor/Drive sections and a feature map (.claude/skills/verify-*/). Several candidates → ask which one; none → stop and point at /create-verification-skill instead of inventing a target.
2. Index hygiene. Read references/features/README.md and glob its sibling files. Fix missing, extra, duplicate, or dead entries. Lightweight; no generated inventory.
3. Source wave. One read-only subagent per feature file, launched concurrently (Agent tool, subagent_type: Explore). Each explains "how does this user-facing feature work?" from source, flags likely doc drift with file:line citations (a data-testid or aria-label the map names that no longer exists is drift), 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.
4. 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 (git log --since=<last pass> -- src/renderer) for user-facing surfaces missing from the map; require a concrete source path before calling one missing.
5. Live pass. Required even when source looks clean. The coordinator owns all driving and follows verify-wmux's launch model: one long-lived isolated instance (control-wmux launch), driven serially, in the sweep order the feature README gives. Exercise every feature at least once, and 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 the first drive, doctor again after any failed drive, and where doctor can't see the failure (a wedged UI state on a healthy process), press --key Escape back to the baseline or stop and relaunch rather than hoping; (2) evidence captured so far survives every cleanup, checked at its named location (.claude/skills/verify-wmux/evidence/<run-id>/), not assumed; (3) nothing a drive started outlives that drive's usefulness: failed-iteration residue (an extra pane, an open dialog, a stray instance) is cleaned whether the drive is stuck or exited. A doctor failure caused by skill drift is drift: fix it under edit scope and retry once, restarting only what the fix invalidated, before calling the pass blocked. A feature that can't be reached is verified-unreachable only with the concrete prerequisite (account, OS, second PC, network, external tool) 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 stop happens after the last drive of the run, including those re-proofs, so nothing outlives the run (evidence stays).
6. 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, unit test for new pure logic). App behavior that's actually broken → product gap; record it for the user, keep it out of this PR. A handle missing only because the installed app is older than the checkout (doctor reports version skew) is skew, not drift: re-drive against a build of the checkout or say so.
7. Ship or stop. For changed: one PR of proven corrections, re-read every changed file first, follow the repo's PR rules (English, no version bump, no changelog fragment for tooling-only changes). 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.