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

Choosing Between Similar Skills

Several pstack skills have similar names or overlapping purposes, and picking the wrong one wastes a run. The quickest way to decide is to ask what is missing right now: something to build or something to repair, an account of how the code works or of why it took this shape, an attack on a design or a plan for carrying it out.

Each section below follows the same pattern. It names the situation in which the two options get confused, says which one to pick, and explains the difference by reference to what each skill’s source file actually instructs the agent to do.

create-verification-skill or maintain-verification-skill

Situation: you cannot rely on agents to prove that your app still behaves correctly.

PickWhen
create-verification-skillThe project has no scripted way to drive the real app, or the existing one should be rebuilt from scratch.
maintain-verification-skillA verification skill already exists, and you want to know whether it still matches the app.

create-verification-skill studies the repository, asking the user only what it cannot observe, and writes a project-local skill at .cursor/skills/verify-<app>/. That skill has sections for launching the app, a read-only “doctor” health check, driving it the way a user would, capturing evidence, and cleaning up. It also seeds a feature map, which is a folder with one file per user-facing feature (3 to 5 to start). The generator then runs the new skill end to end once, because a skill that was never executed counts only as a draft.

maintain-verification-skill is the upkeep loop for that output. It sends one read-only subagent per feature file to check the map against the source, then drives every feature live in one session. Its edits are confined to the verification skill’s own directory, and it never touches product code: a mismatch is classified as doc drift (fix the map), a gap in how the app can be driven (fix the driver), or a product regression (report it to the user). The run ends as clean, changed (at most one PR of proven corrections), or blocked. If it finds no verification skill to maintain, it stops and points you at the create skill instead of inventing a target.

Ordinary verification or formal verification

Situation: you need to decide how strong a claim “it works” has to be.

  • To confirm behavior by running the real app along a user’s path, use ordinary verification: the project’s verification skill together with the Prove It Works principle (check the real artifact, never a proxy such as “it compiles”).
  • To guarantee a property across every case in a stated scope, including cases tests rarely reach, use create-formal-verification-skill.

The formal skill’s own opening draws the line: a test checks the cases someone thought to write, whereas formal verification checks every case within a scope, such as every ordering of steps in a model or every input up to a bound. The question determines the tool. Whether events can occur in a harmful order suits a model checker, with TLA+ as the default; whether the code behaves for every input suits a verifier that runs on the code itself. The skill names concurrency, retries, state machines, parsers, and unsafe code as typical targets, and it asks for the target where a bug costs the most and tests reach the least.

The price of that strength is scope. A pass covers the model or the bound, and the skill must say which assumptions and bounds apply and what lies outside them. In practice, ordinary verification covers everyday changes, while formal verification is reserved for a few promises whose failure would be expensive.

The formal pair has the same create and maintain split as above. maintain-formal-verification-skill handles code changes that skipped the check, such as merges and refactors. It gives each check one outcome (in sync, updated, bug, or blocked) and warns that the dangerous case is a check that keeps passing while it describes code that no longer exists.

how or why

Situation: you are new to a subsystem and want to ask “what is going on here?”

  • To learn how the current code works, or where something should live, use how.
  • To learn why it took this shape, or why it broke recently, use why.

how spawns one read-only subagent that explores the codebase and writes an architectural explanation aimed at a senior engineer who has never seen the area. Its description also covers placement and ownership questions, such as which package should own a piece of code.

why answers from the record instead of the code. It reads the commits and PR discussions that introduced the target and each later change, cites what the authors wrote, labels its own inferences as inferences, and states what the record cannot answer.

Order matters when you use both. The recipes guide runs how first and why second: mechanics before history. Both reports name the sources they searched, so you can see what each answer rests on.

interrogate or figure-it-out

Situation: a large change is coming, and you are unsure whether to attack it or to organize it.

  • To find the weaknesses in an existing change or design, use interrogate.
  • To decide how to carry out large work that no playbook fits, use figure-it-out.

interrogate is adversarial review. It first restates the intent of the change, then sends several adversaries, each in its own worktree, to break it. A finding survives only if the adversary proved it with a run (a failing test, a repro script, or command output) and the rerun confirms it. The skill reports findings and dropped items, and it never applies fixes.

figure-it-out is constructive. Its first deliverable is the workflow itself, before any code. It frames the definition of done as a falsifiable predicate, splits the work into units that can land independently, orders them so the riskiest unknowns come first, builds the verification before the work, and keeps a decision trail through show-me-your-work. Its description names large migrations, ambitious multi-part changes, and work a human reviews after stepping away.

If you doubt a design, choose interrogate; if the work has no procedure yet, choose figure-it-out.

arena or swarm

Situation: you want several agents working at once, and both skills fan out.

  • To get several attempts at the same design or code and combine their strengths, use arena.
  • To cover independent slices in parallel, or race identical workers, and receive one report, use swarm.

arena gives every candidate the same prompt, scores the results against a rubric (with a judge from a different vendor when possible), picks a base, and grafts the best parts of the losing candidates into it by hand. swarm partitions the work into slices or declares a race rule, gives each worker a self-contained brief, and aggregates the results into one table of PASS, ISSUES, or BLOCKED. The pitfalls in the guide warn against using arena for coverage: it repeats one brief, while swarm divides the work.

ketchup or ketchup-video

Situation: you return to a chat that kept working and want to catch up.

  • To read a quick summary in prose, use ketchup.
  • To watch what happened, use ketchup-video.

ketchup is read-only. It covers everything since the last message you wrote, in plain words with screenshots and small diagrams, then lists every call that only you can make (a merge, an approval, a choice between options), each with the agent’s pick, the evidence, and the risk. The goal is that you can decide from the reply alone.

ketchup-video follows the same rules but replaces the summary and visuals with a short, silent, subtitled video built from the screenshots, diffs, and data the work produced, using at most 10 slides. Rendering the video outside the repository is its one exception to the read-only rule. The waiting calls still appear as text under the video. Choose the video when the work is mainly visible change, such as UI appearance or flow transitions, and the text version when words are enough to decide.

sharpen, correct, or unslop

Situation: the output is not good enough, and you want to “fix” something.

PickWhat it repairs
sharpenThe prompt you are about to send is too shallow.
correctAgents keep making the same mistake in this repository.
unslopA piece of writing still reads like AI output.

sharpen does not perform the task. It asks for a “deeper version of this task, not a bigger one”: what a top professional would do that you did not ask for, the rawest material they would start from, their methods and tools, and what outside check would show the result is right. It then rewrites your prompt to ask for exactly that.

correct changes the repository. It mines recent commits, reverts, and review comments for mistake classes (a class counts once it has occurred twice) and fixes each at the highest level that works: architecture first, then types or a lint whose error names the fix, then a test, and documentation last. Each new check must be shown to fail on a real past mistake.

unslop only edits text. It applies a numbered list of rules against stock vocabulary, filler, dashes, vague attributions, and similar habits, while keeping the meaning and tone.

reflect or correct

Situation: a session taught you something, and you want the next run to benefit.

The guide splits the work cleanly. reflect reads one transcript and proposes edits to skills that the session used, sorted into Accepted, Rejected, and Backlog, and waits for your approval before changing anything. correct works on the repository so that a class of mistakes cannot recur. Use reflect to improve the instructions an agent follows, and correct when the fix belongs in code, types, lints, or tests.

Autonomous run, Autopilot-full, or Autopilot-stack

Situation: you want work to continue while you are away, and must decide how much to hand over.

PickWhen
Autonomous run playbookOne task should be driven to a single finish condition.
Autopilot-full playbookA queue of independent PRs should be carried all the way to merged.
Autopilot-stack playbookThe same queue should stop at verified, so that you review and land each PR yourself.

The Autonomous run playbook is a loop around one task. The exit condition is fixed first as a checkable predicate, and every iteration makes the smallest justified change, verifies it, commits it or discards it, and logs one row.

Autopilot-full manages a queue. Each PR gets one owner agent, running in parallel off trunk, that builds, opens the PR, proves the change, and keeps CI green. No owner merges on its own verdict, however: a swarm of verifiers that did not write the code checks the code-ready head, and only a clean verdict on the patch that lands authorizes the merge. Green CI alone never does.

Autopilot-stack runs Autopilot-full but stops once each PR is verified and green, then hands the PRs to you. It also allows one exception to the “never stacked” rule: a PR may be based on another PR’s branch when it builds on that PR.

The scope of the handover decides the choice. “Finish it” means Autopilot-full, “have it ready for me” means Autopilot-stack, and “keep at this one task” means Autonomous run. The overnight chapter covers how to set each of them up.