Skip to content
  1. Skills at a glance
  2. Verify
  3. /pstack:maintain-verification-skill

/pstack:maintain-verification-skill

Call when needed

In one lineAfter the app changes, it checks the verification skill feature by feature and fixes what's stale. It never touches product code.

When to use
Best run once a day. You can make it a scheduled task.
Say it like this
/pstack:maintain-verification-skill

Just asking vs. using it

The same request, typed plainly or with /pstack:maintain-verification-skill. Here's what changes.

Just askingWith /pstack:maintain-verification-skill
Rewrites the docs to cover up a broken feature.Edits only the verification skill's files and reports product bugs to you.
Keeps driving an instance in an unknown state.Runs Doctor after any failed drive before driving again.
Opens a PR even when nothing changed.Opens one PR only for proven changes and names the outcome.

What the document says

3 sections, about 700 words, 3 min to read. Click a section to read it.

OpeningA feature map goes stale when the app changes, so this pass checks every feature in source and runs every feature live.

  1. 1OutcomesEnds in one of three outcomes: clean with no PR, changed with one PR, or blocked with the exact reason.
  2. 2Edit scopeEdits only the verification skill's own folder. Product code stays untouched, and real breakage gets reported to you.
  3. 3PassSeven steps: find the skill, tidy the index, read source per feature, merge, run every feature live, triage, then ship or stop.

See the wording worth borrowingRead the full text

Wording worth borrowing

A few sentences from the original: what each one makes the AI do, why it works, and how you can borrow it.

  1. Say where rigor applies

    The unit of rigor is the feature, not every sentence

    Makes the AI
    It checks every feature without grinding through every sentence and stalling the pass.
    Why it works
    Naming the unit that must be rigorous tells the AI what needs full coverage and what can pass.
    Borrow it
    When the AI proofreads a long doc, write: "Check every chapter, but don't nitpick every word."
  2. Block the tempting skip

    Required even when source looks clean.

    Makes the AI
    Even when the code looks fine, it opens the app and uses every feature.
    Why it works
    Naming the exact case the AI would use as an excuse works better than just saying "required".
    Borrow it
    When the AI checks data, add: "Even if it looks right, spot-check 5 random rows by hand."
  3. Map each case with an arrow

    Several candidates → ask which one; none → stop and point at /pstack:create-verification-skill instead of inventing a target.

    Makes the AI
    With several matches it asks you, with none it stops. It won't pick one or make one up.
    Why it works
    Each case points to its action with an arrow, and every case is listed, so none gets missed.
    Borrow it
    For file cleanup, write: "More than 10 → ask me first; none → tell me, don't create one."
  4. Set a bar for each conclusion

    require a concrete source path before calling one missing

    Makes the AI
    When it says the map is missing a feature, it always gives the code location.
    Why it works
    Saying what evidence a conclusion needs stops the AI from reporting problems on a hunch.
    Borrow it
    When the AI checks a site, write: "Before saying a link is broken, paste the error you got opening it."

Full text

The SKILL.md the AI reads, as written.

descriptionPeriodic 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 /pstack:maintain-verification-skill or "audit the verify 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 /pstack: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).

Pass

  1. Locate the target. Find the verification skill to maintain: the project-local skill whose body has launch/drive sections and a feature map (usually verify-*/ in the project's skill folder: .cursor/skills/, .claude/skills/, .pi/skills/, or .agents/skills/). Several candidates → ask which one; none → stop and point at /pstack:create-verification-skill instead of inventing a target.
  1. Index hygiene. Read the feature map README and glob its sibling files. Fix missing, extra, duplicate, or dead entries. Lightweight; no generated inventory.
  1. 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.
  1. 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.
  1. 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) 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, 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).
  1. 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.
  1. 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.

Original by Lauren Tan (poteto), MIT license. Checked against the pstack mirror at 97de40d. View on GitHub

An unofficial beginner's guide to pstack, not its official docs. pstack is made by poteto; the official repo is the source of truth for commands and behavior. The original guide source is on GitHub.

Hosted by airali. Adapted from Xiaoxiaodong's MIT-licensed guide.