Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Verification

This group of skills turns “it should work” into “I ran it, and here is the evidence”. pstack treats a green build as a claim to be checked, and these skills give an agent the means to check it against the real artifact.

Two ideas sit at the center of the group.

  • A verification skill is a project-local skill, usually at .cursor/skills/verify-<app>/, that tells an agent how to launch this particular app, drive it the way a user would, capture proof, and tear everything down. It is written for an agent that reads it cold in the middle of a task, so it is full of repository-specific facts: the real start command, ports, seed data, stable selectors, and the place where evidence is stored. /create-verification-skill generates one and /maintain-verification-skill keeps it in step with the app.
  • Formal verification checks a property of the code across every case in a stated scope, rather than only the cases someone wrote a test for: every order of steps in a model, every input up to a bound, or every input. /create-formal-verification-skill picks a target and a tool and leaves a project-local skill behind; /maintain-formal-verification-skill brings that check back in line after the code moves.

The remaining 2 skills are disciplines that cut across all kinds of work. /benchmark-checklist vets a performance number before anyone reports it, and /show-me-your-work keeps a reviewable decision log for long or unattended runs.

The verify-and-ship guide page frames the whole group around one observation: verification is usually the slowest step of agent work because it waits on a human. If an agent can do it alone, the human stops being the bottleneck; if the step is skipped, more agents only produce more unchecked work.

Matching the check to the change

Before any of the skills below, the guide asks you to state the finish condition in the first prompt, so that the agent has concrete checks to run. A reply should then carry the exact commands and their output, or say “inconclusive” when a check could not run. The guide pairs each kind of change with the check that fits it:

ChangeCheck
CLIRun the real command.
UIWalk the changed flow in the running app.
Parser or migrationReplay a saved input.
PerformanceCompare profiles taken before and after.
StorageRead the written value back.

The proof should be an artifact you can inspect yourself: a failing test followed by a passing one, a before-and-after video, a trace, or a screenshot. An artifact can be challenged without replaying the whole run, which a plausible explanation cannot.

/create-verification-skill: generate a project-specific way to drive the app

/create-verification-skill produces a verification skill for any language, framework, or platform. Reach for it when you type the command, when you ask for “a control skill for this repo”, or when the project has no scripted way to prove that its UI, CLI, or service behaves correctly.

Interview the repository

The generator answers its questions from the codebase and asks the user only about what it cannot observe. It works through 5 areas:

AreaQuestion
SurfaceWhat does a user actually touch: a web UI, a CLI or TUI, a desktop app, an API, a mobile app, a library? If there are several, pick the primary one and note the rest.
RunHow does the app start locally? Prefer the repository’s own documented dev command, and note ports, environment variables, seed data, and authentication.
DriveHow can an agent operate it from a program? Look for existing tooling first (Playwright or Cypress specs, expect scripts, PTY helpers, endpoints reachable with curl, a debug port). Only then fall back to a generic recipe: a browser over CDP for web and Electron, a tmux or PTY session for CLIs and TUIs, plain HTTP for services.
ObserveWhat evidence can be captured: screenshots, terminal transcripts, response bodies, logs, exit codes, database state?
IsolateCan 2 instances run side by side? If not, the generated skill must say so and refuse to drive a shared instance twice, since corrupting the user’s session is worse than declining.

If the checkout does not build or start as it is, the generator fixes that first or reports it precisely, because a skill written against a broken base teaches the wrong steps. When an irrelevant missing asset blocks startup (for example a static directory the API never serves), the generated skill may create it, provided it is clearly labeled as verification scaffolding and removed during cleanup.

Write the skill

The output is .cursor/skills/verify-<app>/SKILL.md. It needs YAML frontmatter with name: verify-<app> and a description naming the app, the surface, and when to use it; without frontmatter the skill never registers. Every section must be filled with what the interview actually found, with no placeholders left behind.

  • Launch: the exact start command and the signal that the app is ready. Ready means usable, not merely that a process responds, so the launch must reach a working state from an empty data directory, migrations and seed data included. For a short-lived CLI, launch means building once and then starting each drive in its own isolated PTY or tmux session.
  • Doctor: a single read-only check answering whether this instance is worth driving (process up, correct build, port owned by this run, authentication valid). Agents run it first whenever anything looks wrong.
  • Drive: the real selectors and commands from this repository. Stable handles such as ARIA labels, data attributes, prompt strings, and route paths are preferred over coordinates or tab order.
  • Evidence: what to capture and where it goes, plus the proof standards. A proof follows the real user path, never internal setters or test-only endpoints; it captures both the action and the resulting state; it checks side effects such as files written or rows inserted; and it uses mocks only where a production boundary already isolates the external system. A dry-run mode must be checked by observation, since some dry-runs still touch the network.
  • Cleanup: stop only what this run started, never by process name. Cleanup removes instances and scratch state but never the evidence, which stays at a location the skill names.
  • Helpers: any shipped script is executable, and the skill body shows how to call it.

Seed the feature map

The feature map is a directory, features/, that indexes what the app does and what observable result proves each feature works. The generator writes features/README.md plus one file for each of the top 3 to 5 user-facing features it can find in routes, commands, menus, or docs. Every feature file uses the same 4 H2 headings: Sub-features, How to get to it (user POV), Driving it with <harness>, and Gotchas. The skill ships a worked example for an imaginary Notes app, whose README also sets baseline preconditions, driving conventions, and rules for reporting skipped paths.

If the seed data lacks a precondition that a user journey needs, the journey reports a failure and the reason goes into that feature’s Gotchas. The journey is never weakened so that it passes. Because the map is the maintained source of truth, a proof that drives one convenient entry point is incomplete when the map lists others.

Prove it before handing over

The generator runs its own output end to end once: launch, doctor, drive one mapped feature, capture evidence, clean up, and then confirm that the evidence still exists at the named location. A cleanup that deletes the proof fails this step. The generated cleanup also runs after every failed attempt, so broken iterations do not leave processes or ports behind. A skill that has never been executed counts as a draft. If the proof ran in a stand-in for the real target (a container instead of a fresh VM, for instance), the handover lists every setup step the stand-in performed that the real target will not, and those steps remain unverified.

Finally, the generator points the user at /maintain-verification-skill and suggests a cadence only when asked.

Using it afterwards

Once the skill exists, “verify it in the app” becomes a step any agent can execute without a setup conversation. The guide suggests naming it in the prompt when you want proof in a particular form, for example use /verify-<app> to verify your changes and show me a video and screenshots as proof. It also recommends committing the skill so that the whole team drives the app the same way, and, when agents keep writing throwaway click-through scripts, asking for a small control CLI that the skill can call instead. According to the guide, a CLI that agents use well has a few composable commands, --dry-run on anything destructive, subcommands that reveal features gradually, error messages that say what to do, rich --help text, and machine-readable output such as JSON.

/maintain-verification-skill: keep the skill and its feature map honest

A feature map starts to decay the moment the app changes. /maintain-verification-skill is the upkeep pass for a skill made by /create-verification-skill, or for any project-local verification skill that has a feature map. The guide recommends running it at least once a day, ideally from a scheduled automation. Its unit of rigor is the feature: every feature file gets source coverage and live coverage, but not every sentence is re-proved.

Outcomes and scope

Each pass ends with exactly one outcome, which the agent names:

OutcomeMeaning
cleanEvery feature had source and live coverage, and nothing needs shipping. No branch, no PR.
changedOne PR of proven corrections to docs, driving scripts, or the map.
blockedCoverage could not finish, or a proven fix could not ship safely. The report says exactly what blocked it.

The pass edits only the verification skill’s own directory. It never touches product code. When the map describes behavior the app no longer has, that is either doc drift (fix the map) or a product regression (report it and do not hide it with a doc edit).

The pass

  1. Locate the target: a project skill with launch and drive sections and a feature map, usually under .cursor/skills/verify-*/. With several candidates, ask which one; with none, stop and point at /create-verification-skill.
  2. Index hygiene: compare the feature map README with the files beside it and fix missing, extra, duplicate, or dead entries.
  3. Source wave: launch one read-only subagent per feature file, all at once. Each explains from source how the feature works, flags likely drift with citations, and returns one live-verification recipe. These subagents never drive the app and never edit files.
  4. Reconcile: make sure every feature returned a summary, merge overlapping recipes into as few app states as practical, and spot-check the cited drift. Then scan recent changes for user-facing surfaces missing from the map, naming a concrete source path for each.
  5. Live pass: mandatory even when the source looks clean. The coordinating agent does all the driving and follows the skill’s own launch model (one long-lived instance for servers and UIs, a fresh isolated session per drive for short-lived CLIs). It exercises every feature at least once.
  6. Triage: a wrong or missing user-facing description is doc drift and gets fixed; working behavior that the driver cannot reach is a gap in the driving scripts and gets fixed; behavior that is actually broken is a product problem, recorded for the user and kept out of the PR.
  7. Ship or stop: for changed, re-read every changed file and open one PR. For clean or blocked, open nothing and report the outcome and coverage honestly.

The live pass holds 3 invariants throughout, whatever fails:

  • Never drive an instance that has not passed the doctor check since it last behaved unexpectedly. Run the doctor before the first drive, on each fresh session, and after any failed drive; where the doctor cannot see the problem (a stuck UI on a healthy process), reset or relaunch instead of hoping.
  • Evidence captured so far survives every cleanup, and this is checked at its named location.
  • Nothing a drive started outlives its usefulness. Final teardown happens after the last drive, re-proofs included.

A doctor failure caused by drift in the skill counts as drift: fix it within the edit scope, restart only what the fix invalidated, and retry once before declaring the pass blocked. A feature may be marked verified-unreachable only with the concrete missing prerequisite (authentication, entitlement, OS, external state) and the route attempted; if the map does not mention that prerequisite, the omission is itself drift. Run notes stay in a scratch location and are not committed.

/create-formal-verification-skill: formally verify the place where a bug costs most

A verification skill proves the paths you drive, but some bugs live on paths that no user session or test reaches: overlapping retries, a lock that expires mid-write, a state change arriving out of order. /create-formal-verification-skill is for those cases. Its trigger phrases include “model-check this race” and “prove this invariant”, and it fits concurrency, retries, state machines, parsers, and unsafe code.

Choosing the target

The agent studies the code and limits its questions to what it cannot see for itself; when the user points to an area or a bug, that is where it begins. A suitable target is a promise made by the code, one whose failure would hurt users and whose breaking case tests seldom hit. The skill requires the strongest target of this kind in the repository, even though that is frequently not the one easiest to verify.

Letting the question choose the tool

The tool is whichever answers the question most cheaply: a model checker, a proof assistant, an SMT-backed verifier, or something else.

  • “Can events happen in a bad order?” calls for a model checker run against a small model of the design; whatever the language, TLA+ is the default choice here.
  • “Does the code behave for every input?” (memory safety, overflow, a data-structure invariant) suits a verifier that runs on the code itself.
  • If no verifier supports the language, the agent says so and tests the real code with generated inputs, rather than a hand-written model of the function.
  • A property that must hold at every size, where a bound is not enough, may need a proof.

The agent prefers a tool the project’s developers can install and run, and explains its choice to the user.

Quality bar

The skill lists the properties of a trustworthy result:

  • True to the code: every part of the model points to code a reviewer can open, and what the model treats as one indivisible step is one indivisible step in the code.
  • Able to fail: each property is shown failing on a broken variant of the code, such as a removed check or a reordered step, because a check you have never seen fail proves nothing.
  • Findings stay findings: when the current code already breaks the property, the agent reports the counterexample and does not weaken the property or the model. Product code changes only if the user asks.
  • Honest about scope: the report says what was verified, under which bounds and assumptions. A pass covers the model or the bound, not the whole system.
  • Readable without the tool: the property and the harm each fit in one plain sentence, and a counterexample reads as a short sequence of steps in the code’s own terms.
  • Cheap to rerun: one command, a reproducible tool version, and a run short enough to use on every relevant change.
  • Kept in step with the code: the skill records which files and functions each check covers and the commit at which the model was last confirmed to describe them.

The generated skill and the handover

The project-local skill it produces has to equip the next agent for 4 tasks: deciding whether a change affects the verified code, running the check, distinguishing a real bug from a modeling error, and updating the verification when a change is deliberate. The skill also keeps the coverage record and the sync commit, and it instructs the next agent to move the sync commit forward only once it has confirmed that the model agrees with the new code. If the check is a TLA+ model, the skill directs the next agent to interpret results through /statechart, which presents each violation as its shortest path in plain words, and to refer to that skill by name only.

Before handing over, the agent follows the generated skill once on a scratch change that breaks the property in the real code. The check must catch the break; afterwards the scratch change is dropped and the check returns to its earlier state. If the check misses the break, the skill or the model is fixed, never the scratch change. The handover covers what was verified, the tool and why, the bounds, the findings in plain words, how to run the check, and what remains uncovered, followed by a pointer to /maintain-formal-verification-skill.

/maintain-formal-verification-skill: realign the formal check with the code

A formal check proves a property of whatever it describes. If the code changes and the model does not, the check can keep passing while it describes code that no longer exists, and that pass is dangerous precisely because it looks like a proof. /maintain-formal-verification-skill handles the changes that bypassed the generated skill: merges, edits made without it, and drift accumulated across many commits.

Outcomes and scope

Each check gets one outcome:

OutcomeMeaning
in syncNothing since the last sync alters what the check describes, and it passes.
updatedThe code changed, the verification now describes it, and the check passes.
bugThe verification matches the current code, yet the code violates the property. The problem lies in the code itself; it is not drift.
blockedThe check could not be realigned or could not run, with the exact reason.

A check can be both updated and bug. The pass edits only the verification (models, the code that drives the checker, property files, the verify skill) and leaves product code alone unless the user asks. It never weakens a property or a model to make a failure disappear.

The pass

  1. Find the checks. Verify skills have no fixed name, so the agent identifies them by behavior: project skills that run a model checker, prover, or verifier against named code. For each check it collects the property, covered code, bounds and assumptions, command, and sync commit. Without any verify skill it stops and points at /create-formal-verification-skill; without a recorded sync commit it uses the last commit that touched the verification files and says so.
  2. Run as it is. Each check runs once before anything changes. A pass at this point only shows that the old description still holds, and a failure could be drift or a bug; the judgement waits until step 5.
  3. Read every change to covered code. The agent diffs the covered files from the sync commit, reads the commit messages, follows code that was renamed, split, or moved, and looks for new code touching the guarded state. Each change is classified as having no effect, as making the model no longer match, as an intentional change of promise (with evidence from doc comments, tests, changelog, or commit message), or as a promise that may now be broken.
  4. Update from the code, not from the result. The model is rewritten from the code before rerunning, never shaped by what makes the check pass. A property changes only for an intentional change of promise, with the old wording, new wording, and evidence written down. Bounds stay as they were unless the change makes them wrong, and any reduction is reported.
  5. Rerun and judge. On a pass, the agent breaks the new code the way the property guards against and confirms that the check still catches it. On a failure, it replays the counterexample step by step against the real code: a step that cannot happen means the model is wrong; if every step can happen, it is a bug, reported with the commit that introduced it, the steps in the code’s own words, and the harm in one sentence.
  6. Update the verify skill. Coverage, commands, bounds, assumptions, and the sync commit are refreshed, except that a blocked check keeps its old sync commit. The agent then follows the verify skill once as the next agent would.

The report states, check by check, which failures were drift in the verification and which were bugs in the code. A check that passed before the update and fails after it is reported as an old pass on a stale description. Verification updates go into a change of their own, separate from any product fix.

/benchmark-checklist: vet a performance number before reporting it

Of all kinds of evidence, a before-and-after number is the one most easily got wrong by accident. A warm cache, a debug build on only one side, or work that never executed inside the timed region can each create a speedup that looks convincing. /benchmark-checklist is required whenever you produce a performance number, whether that is a PR’s before and after, a claim of regression, a hill-climbing measurement script, or a comparison of libraries or configurations. Each answer has to come from an actual run rather than from reasoning about the code. The guide describes it as the practical form of the Explain the Number principle.

Before running anything

  • Write down the claim you expect to ship, such as “export is 30% faster at p50 on the 60k-row dataset”. The questions test that sentence.
  • Read the measurement script and note what it times, counts, and ignores.
  • Check load with uptime and cores with nproc. If the machine is busy and the load cannot be stopped, interleave the 2 sides so both see the same noise, and say so.

The 7 questions

#QuestionWhat it demands
1Why not double?Name the limiter with profiling in a run you do not report (CPU per process, a runtime profiler, I/O wait, syscall counts). Check that the load generator is not the bottleneck. If a change did not move the number, the limiter explains why.
2Was it tuned?Every side runs as production does: release builds, production flags, pools, caches, the same versions and data. If one side runs on defaults, you compared configurations. A limiter that is really a setting means that side must be tuned and remeasured before a winner is chosen.
3Did it break limits?Check the arithmetic against core counts and against disk and network bandwidth. If a piece accounts for 10% of the run, eliminating it can speed the run up by roughly 11% at most. A result beyond a physical limit was measuring something different, for example a cache or a no-op.
4Did it error?Count the failures and every response that was not a success, and confirm that the outputs are correct as well as present. Rejected requests usually return quickly, while retries take longer.
5Does it reproduce?At least 5 runs per side, alternating A, B, A, B. Report the median and range; a gap smaller than run-to-run variation is no measurable difference. Use a rank-sum test when the call is close.
6Does it matter?Measure the end-to-end path a user waits on and express any micro result as a share of it. A helper that takes 1% of a request can save at most 1%.
7Did it even happen?Confirm that the work ran inside the timed region. Unconsumed generators, unawaited promises, results the JIT can discard, and timeouts all produce numbers for work that never happened.

For a quick ballpark that the user explicitly asked for, one run is enough, but questions 4 and 7 still apply and the report says it was a single run. A choice between options never counts as a ballpark.

The report

The report leads with one of 4 verdicts: faster, slower, no measurable difference, or inconclusive. It gives the number with its unit, the run count, the range, and the limiter. The verdict is inconclusive whenever a difference is claimed but the limiter cannot be named, a side ran untuned, or questions 4 and 7 could not be checked. A PR body carries a single primary number, with the detailed runs in a linked artifact.

Inside /poteto-mode, the Perf issue and Hillclimb playbooks already run this checklist (the former vets its baseline, the latter vets its measurement script before freezing it), so you type it yourself mainly for numbers measured outside those playbooks or for someone else’s result that looks too good.

/show-me-your-work: leave a decision log for long or unattended work

/show-me-your-work keeps one canonical log for autonomous, multi-phase, or unattended runs, so that a human returning later can review why the agent did what it did. Other skills route their audit trails here instead of inventing their own format.

The format

The log is a single TSV file with one row per decision, single-line cells, and evidence given as a pointer rather than prose. A header template is provided.

ColumnContent
tsISO 8601 timestamp
phasePhase or workstream
decisionWhat was chosen or done, in one line
whyThe reason in plain words; a principle that drove it is stated plainly, not as a tag
evidenceCommit SHA, PR number, file:line, or artifact path; never a paragraph
resultOutcome or predicate state, such as tests green, reverted, pixel-diff 0, INCONCLUSIVE, open

Rows are written as you would tell a teammate what happened, with the unslop skill applied to the text. The helper scripts/log.sh <logfile> <phase> <decision> <why> <evidence> <result> adds the timestamp, writes the header on first use, strips stray tabs and newlines, and prefixes cells that begin with =, +, -, or @ with a quote so that spreadsheets do not treat them as formulas.

What to log and where

Record decision points rather than each individual action: a fork that was taken, a finished unit together with its verification result, a pivot or revert with what caused it, a blocker, or a gate that was repaired. A loop run gets one row for each iteration.

A run is one agent conversation, including its later turns. When a run appends to a log that already holds rows, its first row has the phase start, naming the timestamp range of earlier rows it did not write and identifying itself in the evidence column. A run returning to a log in a later turn first reads the last rows to see whether another run has written since.

Unless told otherwise, the log is a local working file (decisions.tsv, or .audit/<task-slug>.tsv if several efforts are running in parallel) that is kept out of git. It is committed only for work so ambitious that a reviewer must follow the trail before trusting the outcome. Rows are only ever appended: a mistaken decision is corrected by a new row that replaces it, and earlier rows are never changed or removed. Evidence from committed scripts is favored over evidence from one-off commands.

Audit and cross-model review

Before handing back, the agent audits its own rows against this run’s transcript in the active workspace’s agent-transcripts/ directory, and deliberately avoids globbing other projects’ transcripts, which would read unrelated private chats. It checks that every row maps to a real decision, that every evidence pointer resolves and shows what the row claims, and that no shaping fork or abandoned approach is missing. Corrections are new superseding rows; even an invented row is never removed.

The agent then spawns a reviewer subagent on a model from another vendor, since self-review does not count. The reviewer reads the trail and transcript and flags weak or missing evidence, verification claimed without proof, choices that look risky in hindsight, and anything a casual reader would miss. Every reply for a run with a trail ends with an “Attention” section that starts with reviewed by <model> and lists the flags; “No flags” is acceptable, but the model name is required.

To read a trail, go top to bottom, follow the evidence pointers, and spot-check. GitHub renders a committed TSV as a table, and column -s$'\t' -t decisions.tsv does the same in a terminal.