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

Introduction: What pstack Is

pstack is a collection of skills that shapes how an AI coding agent works. Instead of improvising instructions in every prompt, it packages working methods as reusable files: 58 skills and 22 playbooks, all written as plain Markdown that an agent reads and follows.

A skill is a folder with a SKILL.md file that tells an agent how to carry out one kind of task. A playbook is a short, ordered procedure for one type of work, such as fixing a bug or opening a pull request. The next chapter explains how the two fit together.

About this book

This book is an independent reconstruction. It was written from the public pstack files in the pstack directory of the cursor/plugins repository at commit e58dd04 (full hash e58dd043600587dbaf58ba315e7f2b38373eeb43). The plugin manifest at that commit gives the version as 0.15.44.

Every fact in the book comes from those files: the README, the guide under docs/guide/, the skill and playbook definitions, the subagent definitions, and the automation pack. The book explains them in its own words and links each skill or playbook to its source file at that commit. pstack changes often, so a newer version may differ from what is described here.

pstack is released under the MIT License. The license file and the plugin manifest name Lauren Tan as the author. The README is written in the first person by an author who signs as “poteto” and gives the skills their names (poteto-mode, poteto-agent, poteto-help).

The problem pstack addresses

The README opens with a familiar complaint: AI agents tend to produce too much “slop”, code and prose that look plausible but carry little value. An agent can write a large diff quickly, yet every unverified line adds to the reviewer’s burden.

The author describes pstack as the set of skills used every day to ship code at Cursor, and states the guiding idea in one line: “if you want to go fast, go deep first.” The README also introduces the author as someone who has worked with millions of lines of code at Meta, Netflix, and Cursor, and who helps build and maintain React Compiler as a member of the React core team.

Three promises

The README makes three claims, each of which the rest of the book returns to.

  1. Less, but better, code. The goal is explicitly not to maximize lines of code. pstack aims for smaller changes of higher quality.
  2. Fearless parallelism. Once you can trust one agent to write good, verifiable code, you can run several agents at once with confidence. Quality is presented as the precondition for speed.
  3. Many models, each used for its strengths. pstack works with any model, and several skills deliberately send the same work to models from different vendors and compare the results.

Ideas that recur across the skills

Five ideas appear again and again in the skills, playbooks, and principles. Each corresponds to one or more of the 24 principle skills, which later chapters cover in detail.

  1. No evidence, no “done”. “It compiles” is not proof. The Prove It Works principle asks for verification against the real artifact: run the feature, read the actual value, inspect the diff. A result that is neither a pass nor a fail is reported as “inconclusive”, never rounded up to success.
  2. The author does not grade its own work. /poteto-mode treats a second opinion as “the same prompt on another vendor’s model”. Review panels mix vendors, and in the Autopilot-full playbook no owner merges a PR on its own verdict.
  3. Subtract before you add. Remove dead weight first, then build on the simpler base. When a new internal API replaces an old one, callers are migrated and the old API is deleted in the same wave.
  4. The human is not a bottleneck. Reversible work proceeds without asking; the human corrects course after seeing the result. Confirmation is reserved for irreversible actions such as a force-push to a shared branch, a deploy, data deletion, or a message to a customer.
  5. Lessons go into structure. When you notice yourself writing the same instruction a second time, encode it as a lint, a runtime check, a metadata flag, or a script instead of adding more text.

Who this book is for

The book assumes you use Cursor or Claude Code and want to hand larger tasks to an agent with less anxiety. Familiarity with Git, branches, and pull requests will help.

Read the next chapter, Overview and the four layers, before anything else. It gives you the map that the remaining chapters fill in.

Overview and the Four Layers

pstack ships 58 skills and 22 playbooks. The numbers look intimidating, but they are arranged in four layers, and once you see the layers you will find that daily use requires you to remember very little.

The four layers

LayerWhat it isCountHow you reach it
1. Entry point/poteto-mode1 skillYou pick it from the / menu
2. PlaybooksStep-by-step procedures inside /poteto-mode22/poteto-mode matches one to your task
3. SkillsIndividual tools such as /how or /swarm33 skillsCalled by playbook steps, or typed directly
4. PrinciplesOne rule per skill, named principle-*24 skillsRead by /poteto-mode; named by you to steer

The 1 entry point, the 33 other skills, and the 24 principles add up to the 58 skill folders under skills/.

Layer 1: the entry point

The only command a human really needs is /poteto-mode. You select it at the start of a task and describe the task in ordinary language. Its frontmatter sets disable-model-invocation: true, so an agent does not switch it on by itself; it runs because you chose it.

Layer 2: playbooks

Playbooks live in skills/poteto-mode/playbooks/ and are not slash commands. /poteto-mode reads your request, picks the matching playbook, and copies its steps verbatim into the todo list as the first items. A bug fix therefore always starts from the same sequence (reproduce, find the root cause, fix, verify on the same surface), whichever agent runs it.

When no playbook fits, or the work is large, cross-cutting, or unattended, /poteto-mode routes it to the figure-it-out skill, which designs a dedicated, auditable playbook for that task. The chapter Playbooks covers all 22.

Layer 3: skills

Skills are the tools that playbook steps call: explaining a subsystem (/how), sending one task to several models and combining the best parts (/arena), running many workers in parallel (/swarm), or asking other models to break a diff (/interrogate). You can type any of them directly, but the README says the other skills are “situational” and that /poteto-mode runs them for you as needed. The chapter Skills describes each one.

Layer 4: principles

Each principle is a short skill that states one rule, grouped as core, architecture, verification, delegation, or meta. /poteto-mode contains an inline index of all 24 and reads it at the start of every task. In its replies it must name each principle that shaped a decision and the specific choice that principle changed, and it may cite only principles whose full file it read in that session.

This makes the principles a shared vocabulary. Because the agent names them, you can name them back: “that does not meet Prove It Works” is a short and precise correction. The chapter Principles covers them.

Supporting parts

Two subagents and one automation pack sit behind the four layers.

  • poteto-agent is the subagent type for delegates spawned during a /poteto-mode run. Before doing any work it reads the poteto-mode skill in full, including the principles index, so delegated work follows the same style. The README warns that substituting a general-purpose subagent skips that read and “drifts”, and that poteto-agent must not be spawned to run the playbook itself. The chat that received /poteto-mode owns the playbook, the todo list, and every spawn.
  • Comment Sicko is a read-only reviewer that hunts for comments to delete. It keeps only a short list of exceptions (license headers, public API doc comments, constraints imposed by something outside the codebase, and a few others) and marks code that needs a comment to be understood as MUST KILL, meaning it should be renamed, extracted, typed, or restructured. It never edits code. You normally reach it through /no-comments.
  • benny is a dormant pack of automations that handles issue reports from Slack: one automation triages incoming reports, and a second one reproduces the bugs that triage confirms and may draft a small fix. None of its files become slash skills. During setup the pack is copied to .cursor/automations/benny/ in the target repository; since it depends on Cursor Automations, it runs only in Cursor.

What pstack relies on but does not bundle

/poteto-mode refers to a few tools that ship elsewhere. The README lists them:

  • /deslop and the deslop skill, which /poteto-mode runs before a commit, come from the cursor-team-kit plugin.
  • control-cli (for command-line tools and terminal UIs) and control-ui (for browsers, Electron, and the web), used when shipping UI or CLI work, also come from cursor-team-kit.
  • /create-skill is built into Cursor. Cursor also has a built-in /autopilot that watches a pull request, but inside /poteto-mode a request for PR status goes to the Babysit playbook instead.

Install cursor-team-kit next to pstack if you want the full set.

Why there are no planning skills

pstack deliberately has no skill dedicated to writing a plan. The README points out that Cursor already has a plan mode that works well with pstack, and then states the author’s own view: “i don’t believe in planning. the best spec is code.”

The same attitude runs through the skills. When a design question can be settled by an experiment, /poteto-mode builds a throwaway prototype (the Prototype playbook) instead of asking or debating. A plan is still available when the work genuinely spans phases or stacked pull requests: the Multi-phase plan playbook covers it, but it is not the default.

Installation and Setup

Setting up pstack takes one install command and one short conversation about models. This chapter covers Cursor first and then the differences in Claude Code, which is the only other host the plugin documents.

Install in Cursor

In a Cursor chat, run:

/add-plugin pstack

Cursor confirms that the plugin is installed. Each skill is a plain file at skills/<name>/SKILL.md inside the plugin, so you can read any of them to see exactly what the agent will be told.

Install in Claude Code

In Claude Code, add the marketplace and then install the plugin:

/plugin marketplace add cursor/plugins
/plugin install pstack@cursor-plugins

Three differences follow from this.

  1. Names take a prefix. Claude Code prefixes plugin commands and agents, so /poteto-mode becomes /pstack:poteto-mode and setup becomes /pstack:setup-pstack.
  2. Updates are manual by default. For third-party marketplaces, Claude Code does not turn on auto-update, which means pstack remains at whichever version you installed. You can switch it on through /plugin: go to the marketplaces tab, pick cursor-plugins, and choose enable auto-update. For a single manual update, run claude plugin update pstack@cursor-plugins.
  3. Cursor-only steps are skipped. When a step needs a feature that exists only in Cursor, such as Bugbot, Cursor Automations, or Cursor cloud agents, the agent writes a one-line note in the form Skipped in Claude Code: <step>. <reason>. and moves on. It does not stop, ask, or retry.

Because the skills are written with Cursor’s tool and path names, pstack includes a Claude Code adapter that the agent reads once per session. It maps each Cursor name to its Claude Code equivalent. A few examples:

In the skills (Cursor)In Claude Code
TaskAgent
AskQuestionAskUserQuestion (plain text in -p mode)
subagent_type: "poteto-agent"pstack:poteto-agent
environment: "cloud"isolation: "worktree"
.cursor/skills/.claude/skills/
.cursor/rules/*.mdc (always-applied rules)CLAUDE.md, or AGENTS.md when there is no CLAUDE.md

The adapter also says that a non-Claude model slug, such as a Gemini model, cannot be passed in Claude Code. The agent omits the model field, so that subagent runs on the session model, and says so.

What /setup-pstack does

Run /setup-pstack once after installing. It decides which model fills each role (a kind of work that pstack delegates, such as bug-fix code or review) and writes the answer to a small rule file that every pstack skill reads.

The steps are:

  1. Detect. It lists the model slugs that a subagent can actually use in this session. It never writes a slug it has not confirmed. If it cannot detect any, it asks you to paste them.
  2. Load. If a rule file already exists, it treats the recorded budget and role values as your current choices. Lines for retired roles are dropped, and recognized old defaults (for example an older Gemini panel seat) are replaced. It tells you which values it changed.
  3. Ask for a budget and confirm. It offers 3 reasoning budgets: large (xhigh reasoning), medium (high reasoning), and small (medium reasoning). It then shows every role with its model and asks whether to accept the list or change specific roles.
  4. Validate. Every real slug must be in the detected set and at xhigh or below.
  5. Write. It overwrites the whole rule file, so that running setup again gives the same result.

The rule file goes to a different place in each host:

HostRule file
Cursor~/.cursor/rules/pstack-models.mdc (with alwaysApply: true)
Claude Code~/.claude/rules/pstack-models.md (no frontmatter)

The rule applies to new sessions, so start a new chat after setup.

Overrides and reruns

You override only what you care about. A role with no line in the file keeps the skill’s default, so deleting a line restores that default.

A rerun keeps every role whose model differs from the default. When pstack changes a default, a file written earlier still pins the old value until you run /setup-pstack again; that run replaces the old defaults it recognizes and reports which. To drop a pinned value it does not recognize, delete that line or the whole file first.

How the model roles work

The rule file has one line per role. The default file, which matches the large budget, looks like this:

# defaults: 3
# budget: large (xhigh)
feature, refactoring: claude-opus-5-5-xhigh-fast
bug-fix: claude-opus-5-5-xhigh-fast
perf-issue: claude-opus-5-5-xhigh-fast
hillclimb: claude-opus-5-5-xhigh-fast
judgment and prose: claude-opus-5-5-xhigh-fast
arena runners: claude-fable-5-2-high, claude-opus-5-5-high-fast, gemini-4-neon-high
arena cross-judge pool: claude-opus-5-5-high-fast, gemini-4-neon-high
swarm workers: claude-opus-5-5-high-fast
interrogate reviewers: claude-fable-5-2-high, claude-opus-5-5-high-fast, gemini-4-neon-high

The roles fall into three groups:

  • Code delegates. Each code playbook reads its own line: feature, refactoring, bug-fix, perf-issue, or hillclimb. All default to Opus 5.5 at xhigh.
  • Judgment and prose. Writing and decisions also default to Opus 5.5 at xhigh.
  • Panels and workers. The /arena and /interrogate panels default to 3 seats from 3 model families: Fable 5.2, Opus 5.5, and Gemini 4 Neon, each at high. swarm workers is the default model for every /swarm worker and for trivial mechanical edits; verification also runs on it.

A few rules hold across all roles:

  • No role runs above xhigh.
  • medium lowers each role one effort level and small lowers it two, on the ladder xhigh, high, medium, low. Both spend fewer tokens.
  • Opus 5.5 always runs its -fast slug. A Gemini seat never runs above gemini-4-neon-high.
  • Outside a panel, Fable 5.2 runs only when you name it for the task, or after two Opus 5.5 runs of the same brief have failed their check. Difficulty alone never qualifies.

Panels, judges, and the parent model

A panel role is a list, and pstack runs one subagent per entry, so the length of the list sets the size of the panel. The arena cross-judge pool is also a list, but /arena runs only 1 judge. It takes the first entry from a vendor other than the parent chat’s vendor, and Fable counts as the same vendor as the other Claude models.

If you use Cursor’s Auto setting, write inherit-parent or auto as a role’s value. Both mean the same thing: pstack omits the subagent’s model field, so the role runs on the parent chat’s model. An alias entry in a panel list still counts toward the panel size, but it never acts as the cross-judge.

Keeping the cost in check

pstack spends extra tokens on subagents and review panels; the guide calls that the price of the rigor. To spend less:

  • Rerun /setup-pstack with a smaller budget or cheaper models. The guide suggests a strong model in the main chat and cheaper, faster models in the code roles.
  • Set a role to auto or inherit-parent so it runs on the chat’s own model.
  • Shorten a panel list, since each entry runs one subagent.
  • Keep /poteto-mode for work that needs rigor. A small, obvious edit does not.

Two optional offers at the end of setup

Setup ends with two offers, each made once.

First, if the project has no way to drive the real app for proof (no verify-* skill and no existing test rig of that kind), setup offers to run /create-verification-skill. That skill writes .cursor/skills/verify-<app>/, a project-local skill that teaches agents to launch your app, use it the way a user does, and capture evidence. It runs the new skill end to end once before handing it over, because a generated skill that was never executed counts only as a draft.

Second, if the project does not have one yet, setup offers to run /create-formal-verification-skill. Tests cover only the cases that someone remembered to write, whereas a formal verification skill checks a single key property, such as “a job never runs twice at once”, across every case inside a declared scope. The guide suggests it for code involving concurrency, retries, a state machine, or a parser: places where bugs are expensive and tests seldom hit the failing case.

If you decline either offer, setup moves on, and you can run the skill later. For newcomers the guide recommends accepting the first offer: an agent that can check its own work keeps going until the check passes, whereas one that cannot hands every result back to you. Of everything in the guide, it says, the verification skill pays off the most. The chapter Verification skills covers both kinds in depth.

Your first task

Pick something real but small and describe it the way you would to a colleague:

/poteto-mode add a --json flag to this command. text output stays byte-identical. verify both.

Watch the todo list: its first items are the steps of the matched playbook, which for this prompt is Feature. The next chapter explains how /poteto-mode reaches that choice and how to write prompts for it.

Using /poteto-mode

/poteto-mode is the front door to pstack. It takes a goal, matches it to one of 22 playbooks, copies that playbook’s steps into the todo list, and calls the other skills as each step needs them. This chapter covers how to start it, how to write a prompt for it, the rules it follows while it works, and how to steer, pause, and resume it.

Starting it

In Cursor, pick /poteto-mode from the / menu before you type the task, so that Cursor attaches the skill to the message. Plain Enter attaches it to that one message only, and its influence fades as the chat moves on.

If you want it active for the entire chat, select it from the menu and confirm with Option+Enter (Mac) or Alt+Enter (Windows) rather than Enter. The skill then becomes a Custom Mode: it remains in context on every turn until you exit the mode. Custom Modes are available in Cursor’s Agents Window and CLI. Claude Code uses the command /pstack:poteto-mode.

The README also notes that /poteto-mode works well with Cursor’s built-in /loop command, which lets an agent keep working for many hours. /loop is part of Cursor, not a pstack skill.

Writing the prompt

You do not write a specification. You state what is wrong or what you want, the way you would brief a colleague. The guide lists up to 5 elements of a useful prompt, each of which fits in one sentence:

ElementWhat it means
The goalWhat is wrong, or what you want.
The done checkA condition that can pass or fail. “Make it better” and “work on it for an hour” are not checks.
The proof you wantOutput from a real command, a recording of the flow, the value as stored, or a number measured before and after.
What you already knowA symptom, a repro step, a log line, or a link; each one saves the agent a search.
The real constraintsPhrases such as “repro first”, “don’t change any code yet”, “zero behavior change”, or “let me review before proceeding”, each of which changes what the agent does.

The guide’s example contains all 5:

/poteto-mode the csv export drops its last row since yesterday's deploy. failing job id is 4812. repro first, then fix. done means the 60k-row fixture exports every row. show me the row counts before and after.

What to leave out

Two things are better left out of the first prompt.

  • The method. Describe the outcome you need and let the agent look for a route that may be better than the one you had in mind.
  • Your theory of the cause. A stated guess narrows the search to wherever you pointed. Let the agent restate the problem first; if it has misread something, the misreading shows up before any code exists and costs one message to correct.

When the input is noisy, for instance a long thread or a loosely described bug, ask for the restatement before anything else:

/poteto-mode read this thread. restate the underlying issue in your own words, in plain english. don't change any code yet.

If you want only the restatement, without a playbook, use /in-your-own-words.

Do not list skills in your prompt. A hand-written sequence such as “use /architect, then /arena, then /interrogate” tends to reorder or drop steps that the playbook would have kept. Name a skill only when you want to override one specific choice.

If you are unsure whether a prompt is aimed correctly, run /sharpen on it first. It describes what a top professional would do that you did not ask for, the raw material and methods they would use, and an outside check on the result, then hands back a rewritten prompt that is deeper rather than longer. It does not carry out the task; you read the rewrite and send it yourself.

Short follow-ups and new tasks

Once the chat already holds the context, a follow-up can be tiny: “/poteto-mode do it”, “continue”, or “keep going until done” are all enough. Short prompts work because the playbook holds the structure.

A long chat accumulates context from the previous task. When you change subject, say “new task”, which makes /poteto-mode match a playbook again instead of continuing the old one:

/poteto-mode new task. figure out why the cache entry survives logout. don't change any code yet.

Here “don’t change any code yet” also pins the new task to the Investigation playbook. Without both phrases, an agent in the middle of a feature tends to treat your question as the next feature step.

What happens after you send it

The sequence is fixed:

  1. On the first message, the agent restates your goal and the smallest change that meets it, then proceeds.
  2. It reads the principles index and matches the task to a playbook.
  3. It opens the playbook file and copies its steps into the todo list first.
  4. It works through the steps, calling skills as they fire, and names in its reply each principle that shaped a decision.

The common routes are:

Kind of taskPlaybook
A read-only questionInvestigation
A defectBug fix
New or changed behaviorFeature
A change to structure onlyRefactoring
Measured slownessPerf issue
Large, cross-cutting, or unattended work, or no matchthe figure-it-out skill

The remaining playbooks cover hillclimbing a metric, runtime and trace forensics, prototypes, visual parity, authoring and evaluating skills, babysitting a PR, shipping a verified stack, autonomous runs, the two autopilot modes, session pickup, pausing, multi-phase plans, worktree cleanup, and opening a PR. The chapter Playbooks covers each.

The rules it works by

/poteto-mode carries a short list of fixed triggers, which it calls its non-negotiables. A few of them explain much of its behavior:

  • Prototype instead of asking. A decision that running something could settle is prototyped (the Prototype playbook) instead of being put to you.
  • Data shape first. Before code, it names the data shape. Code that crosses a function boundary goes through /architect; fan-out goes to /swarm, a bake-off to /arena, and a contested design to /interrogate.
  • Prose is cleaned. Every piece of prose, the reply included, goes through /unslop; docs, PR descriptions, and commit messages also go through /technical-writing.
  • Before commit and review. It runs /deslop (from cursor-team-kit) before committing and /no-comments before review.
  • Numbers are vetted. Any number it measured goes through /benchmark-checklist.
  • Long work leaves a trail. Long or unattended work keeps a /show-me-your-work decision log.
  • Bot review comments are judged one by one on their merits.

Its replies follow a style rule as well: short declarative sentences, the change for the user first, and every claim labeled with its evidence or as measured, inferred, or a guess. It must never hand you a check that it could run itself. And it is allowed to say no: asked whether to add scope or shown an approach, it gives its real judgment, including “this doesn’t earn its place” when that is true.

Autonomy and the irreversible line

The default is to act. Reversible work and routine external actions (team chat, ticket updates, starting evals) proceed without asking. The agent always pauses before irreversible writes: a force-push to a shared branch, a deploy, data deletion, or a message to a customer.

Phrases such as “don’t stop”, “going to bed”, “run until done”, or “be fully autonomous” are session overrides: they tell the agent to keep going without checking in. They do not remove the pause before irreversible actions.

Steering a run

Because /poteto-mode names the principles behind its decisions, the most efficient correction is to name one back, for example “this doesn’t meet Prove It Works”. A principle name is shorter and more precise than a paragraph of instructions. The chapter Principles lists all 24.

You can also add a constraint mid-run. “Let me review before proceeding” switches the agent to waiting for your approval at that point.

Running agents in parallel

Several agents working in one repository on one machine will compete for the working tree, the ports, and the build output. The guide gives two ways to isolate them:

  • Cloud subagents. Every cloud subagent runs on a dedicated VM and branch, which lets it install dependencies, start the app, and capture video while your own machine stays untouched. Either put /in-cloud in front of the task, or tell the parent chat to delegate work to cloud subagents.
  • Worktrees. When the work must stay local, ask for a fresh worktree and branch per task. Worktrees cost disk space, so a laptop runs only a handful at once. The Opening a PR playbook already works from a worktree for code changes.

When worktrees pile up, the Worktree cleanup playbook classifies each one by merge state, uncommitted work, and which chats still use it. It deletes only what that evidence clears and waits for you on anything holding uncommitted work.

Delegation inside a run

The chat that receives /poteto-mode runs the playbook itself. Any subagent it spawns directly in a playbook step uses the poteto-agent type, except where a routed skill such as /swarm or /interrogate sets its own type.

Every agent it starts receives a kickoff whose first line tells it to read worker.md. That file states the rules a worker follows for the operator, the person the whole run works for. Among them: the bar stated in the kickoff is the whole bar; reversible choices are made and explained instead of being asked about; PRs are opened ready for review, never as drafts, with a type(scope): subject title and a body of at most 40 lines.

The parent owns every subagent’s work: it reviews the diff and writes its own summary. Fix rounds, follow-ups, retries, and the next queue item go to a fresh subagent, which receives the original brief, every later directive, and the previous agent’s report and branch. An existing subagent is resumed only when the work depends on state that lives in it and is costly to move, such as its checkout, its uncommitted changes, or a process it is still running.

Pausing and resuming

To stop on purpose, tell the agent to pause, or that you are about to go offline or restart Cursor. The Pause safely playbook then:

  1. stops at a safe boundary, finishing or backing out of the current step and canceling nested subagents;
  2. takes no irreversible action to pause (no new PR or push);
  3. commits uncommitted edits as one wip: commit on the current branch;
  4. writes a resume note covering intent, progress, what is verified, next steps, key files, and pitfalls.

The pause is explicit only: “keep going” or “going to bed, keep going” never triggers it.

A fresh chat resumes the work through the Session pickup playbook. It reads the previous agent’s trail (a transcript in the active workspace, a cloud agent URL, or a pushed branch), treats that trail as authoritative, and names the resume point without redoing finished work. It then hands the rest to the matching playbook and verifies the inherited claims on the real artifact, because a passing self-report from the previous agent is not proof.

For long or unattended runs, the /show-me-your-work decision log makes the work reviewable when you return. The chapter Running work while you sleep covers that in detail.

Playbooks: An Overview

What a playbook is

A playbook is a written procedure for one kind of task, bundled inside the poteto-mode skill. Each one is a short Markdown file in skills/poteto-mode/playbooks/, and pstack 0.15.44 ships 22 of them.

Playbooks have no slash commands of their own. You type /poteto-mode with a goal, and the chat that receives it picks the matching playbook and runs it itself. The poteto-mode SKILL.md tells that chat to match the task to a playbook, open playbooks/<title>.md with the title in kebab case, and copy the steps into the todolist tool first.

That copying step matters in practice. The procedure becomes a visible checklist at the top of the todo list, so you can follow progress item by item and spot a skipped step early. The setup guide names the todo list as the first thing to watch after your first prompt.

When no playbook fits, or when the work is large, cross-cutting, or unattended, poteto-mode routes it to the figure-it-out skill, which designs a dedicated, auditable procedure for that task.

The shape of a playbook

Most playbooks follow the same three-part pattern.

PartWhat it does
Ownership lineA bold opening sentence that fixes what the agent is responsible for, such as “You own the design.” for Feature or “You own the exit condition.” for Autonomous run.
Numbered stepsThe procedure itself. Steps name the principle skills (principle-*) and workflow skills (architect, arena, swarm, interrogate, and others) that apply at that point.
Reply: lineThe items the final message to the user must contain. The shape of the report is part of the procedure.

The pattern has exceptions. Autopilot-stack opens with a one-line instruction to run Autopilot-full without merging, and Worktree cleanup starts directly with its first step. Babysit and Opening a PR have no Reply: line.

Opening a PR describes itself as “invoked at the end of every other playbook”. Feature, Bug fix, Perf issue, Refactoring, Hillclimb, Visual parity, and Authoring a skill all end with it. The read-only playbooks do not: Investigation states that it opens no PR, and the 2 forensics playbooks deliver a diagnosis without a fix.

How a playbook is selected

The chat that receives /poteto-mode makes the choice from 2 kinds of signal.

  1. The nature of the request. The user guide shows that “repro first” plus a checkable outcome is enough for /poteto-mode to match Bug fix, and that “don’t change any code yet” pins a question to Investigation. You rarely need to name a playbook.
  2. Fixed routes in the Non-negotiables of SKILL.md. A request for PR status goes to the Babysit playbook rather than Cursor’s built-in babysit skill, landing a green stack goes to Shipping, and a design fork that a run could settle goes to Prototype instead of becoming a question to the user.

The playbooks that write code also choose which model writes it. /setup-pstack generates a rule file, ~/.cursor/rules/pstack-models.mdc, with one line per role, and each code playbook reads its own line: feature, refactoring (one shared line), bug-fix, perf-issue, or hillclimb. Prose and judgment work reads judgment and prose, and trivial mechanical edits read swarm workers. A role without a line falls back to the defaults in SKILL.md.

All 22 playbooks

The table follows the grouping used by the next 5 chapters.

PlaybookChapterPurpose in one line
multi-phase-planPlanning and startingWrite an executable plan for a change that spans several PRs; implement nothing.
featurePlanning and startingAdd or change behavior; own the design and verification, delegate the code.
prototypePlanning and startingBuild a throwaway sketch to settle a design or behavioral decision cheaply.
session-pickupPlanning and startingResume a prior agent’s work from its trail without redoing it.
pause-safelyPlanning and startingStop at a safe boundary and leave a note a fresh agent can resume from.
autonomous-runAutonomous executionDefine “done” as a predicate and iterate toward it without stopping.
autopilot-fullAutonomous executionCarry a queue of independent PRs to merged, gated by independent verification.
autopilot-stackAutonomous executionAutopilot-full that stops at verified and leaves merging to the operator.
babysitAutonomous executionDrive a PR or a stack to merge-ready: conflicts, then review threads, then CI.
bug-fixTroubleshootingReproduce, binary-search the cause, and ship the smallest fix the evidence supports.
investigationTroubleshootingAnswer a question read-only, with a cited explanation or a recommendation.
perf-issueTroubleshootingMeasure a baseline, test hypotheses, and tie every fix to a number.
runtime-forensicsTroubleshootingDiagnose a live symptom by instrumenting the running process.
trace-forensicsTroubleshootingDiagnose from a profile, trace, or dump that was already captured.
opening-a-prShippingThe title and body format for a ready PR; the closing step of other playbooks.
shippingShippingVerify each PR in a green stack independently, then land the verified run bottom-up.
hillclimbShippingImprove one metric in a loop: one change, one measurement, keep or revert.
evalShippingCompare variants of a skill or prompt with blinded candidates and a blinded judge.
refactoringImprovement and cleanupChange structure while a pinned contract holds behavior fixed.
visual-parityImprovement and cleanupMigrate UI until an image diff against a frozen baseline is zero.
worktree-cleanupImprovement and cleanupAudit worktrees and simulators, then delete only what the evidence clears.
authoring-a-skillImprovement and cleanupWrite or modify a SKILL.md and validate it.

Choosing a playbook yourself

You can override the automatic choice by naming a playbook in the prompt. The user guide does this for skill changes (/poteto-mode run the eval playbook on this skill change.), and SKILL.md itself routes by name (“PR status → the Babysit playbook”), so naming one is a supported way to work.

When you switch subjects in a long chat, say “new task”. According to the guide, this phrase makes /poteto-mode re-match instead of treating your new question as the next step of the playbook it is already running.

Steer sparingly. The guide warns against listing skills in sequence (“use /architect, then /arena, then /interrogate…”), because the playbook already orders them and a hand-written order tends to drop or reorder steps. Name a skill only when you want to override one specific choice.

Handoffs between playbooks

Several playbooks end by handing work to another, and knowing these routes lets you request a handoff directly.

  • Investigation is read-only. If the answer requires a code change, it hands back to you and re-routes to Bug fix or Feature.
  • Runtime forensics stops at a diagnosis and hands the cause to Bug fix or Perf issue.
  • Prototype hands the chosen direction to Feature, or to architect for the shape.
  • Multi-phase plan settles its open questions through Prototype before writing.
  • Perf issue sends sustained work against a metric to Hillclimb. When a hillclimb runs unattended, it borrows only the wake mechanism from Autonomous run, not its stop rule.
  • Session pickup ends by routing the remaining work to whichever playbook fits it.
  • Refactoring routes a redesign to Feature and large structural work to figure-it-out.

The next 5 chapters cover each playbook in detail: Planning and starting, Autonomous execution, Troubleshooting, Shipping, and Improvement and cleanup.

Playbooks: Planning and Starting

This chapter covers 5 playbooks that sit at the entrance to a larger piece of work. Multi-phase plan produces only a plan. Feature owns a change’s design while delegating its code. Prototype settles a decision with a throwaway sketch. Session pickup resumes another agent’s work, and Pause safely stops work cleanly so it can be resumed later.

Two terms appear throughout:

  • Operator: the human who directs the run and gives the go for execution and irreversible steps.
  • Trunk: the repository’s main branch, which PRs branch from and land on.

Multi-phase plan: a checklist an owner runs box by box

Source: multi-phase-plan.md

This playbook produces the plan for a change that spans several phases or PRs. The plan is the deliverable, and the playbook writes no code. It is meant to be a checklist that an owner works through box by box while the operator audits each box from its evidence.

The user guide recommends asking for a plan only after the design has settled, with a prompt such as turn this design into a plan. small verifiable PRs, each with its own verification steps. If the change touches 1 or 2 files and the approach is obvious, the playbook says so and stops without writing a plan.

The steps:

  1. Settle open questions by prototype (see Prototype below). Ask the operator only about product or preference calls that no run could settle.
  2. Write the plan file. It opens with what changes, the PR ids in landing order, and a dependency graph showing which PRs branch independently from trunk, which wait for others, and which files each may touch.
  3. Give each PR its own section. One PR carries one change with its own evidence, following the principle-sequence-verifiable-units skill. Each section has checkboxes for its dependencies, the files it edits, the single change it builds, the visible result, and its verification.
  4. Return the plan path and stop. Execution begins only on the operator’s explicit go.

Tests by themselves are not verification. A PR counts as verified only once its unit, live, and perf boxes are all ticked. The live box requires driving the real surface through a concrete scenario with a pass predicate. The perf box names the metric and the probe, a trunk baseline taken beforehand, and the value at which the check would fail. If a PR changes an interaction, it does not merge until the operator has reviewed it.

The reply gives the plan path, the PR ids with their dependencies, the set of PRs gated on review, and whatever remains unproven.

Feature: own the design, delegate the typing

Source: feature.md

Feature builds new or changed behavior. The agent owns the design and is responsible for planning, review, and verification, but it delegates the code-writing to a subagent and stays in the lead. A change that crosses a function boundary gets its shape from the architect skill.

The steps:

  1. Trace the affected subsystem, then use architect for the shape.
  2. Write the throughput checkpoint, a set of 4 todo items that decide how the work can be split: blocking first steps (gates that run before any fan-out), independent workstreams (disjoint files or layers that can run in parallel), shared mutable state (split the target by default, per principle-separate-before-serializing-shared-state), and the smallest safe decomposition. A dimension that does not apply keeps its item, marked n/a: <reason>.
  3. Delegate the code to a subagent on the model from the feature, refactoring line of the model config. The brief names file paths, success criteria, and the data shape with its organizing structure, per principle-model-the-domain (a state machine instead of scattered booleans, a table instead of branching). Where several shapes are valid, such as error handling, abstraction layer, or test structure, delegate through the arena skill so competing runners surface the alternatives.
  4. Verify on the matching surface. An “inconclusive” result, or a check on the wrong surface, is flagged and does not count as a pass.
  5. Rebase into small, ordered commits and stack follow-ups, building and verifying each unit before the next.
  6. If the design is contested, run interrogate before shipping.
  7. Run the Opening a PR playbook.

Delegation is mandatory. The playbook allows no “skip with a reason” escape, and the Laziness Protocol does not override it, because the gain is separation between author and reviewer rather than fewer lines. A subagent that is itself forbidden to spawn meets the rule by owning the diff directly.

Tightly coupled work (one feature, one migration) goes to a single owner who keeps the checkpoint inline and fans out internally after the blocking phase. Fan-out at the parent level is reserved for slices that produce independent artifacts, such as audits, cross-subsystem investigations, or competing experiments. At phase boundaries the checkpoint is rewritten, and a fresh owner is spawned rather than chaining interrupts to the old one.

The reply covers what was built, the choices and their reasons, the throughput checkpoint, and open decisions, with design alternatives in tables.

Prototype: settle a decision with a throwaway sketch

Source: prototype.md

Prototype makes a design decision cheaply. Its output is the decision plus a disposable artifact, never shippable code; the real build follows the Feature playbook. It applies to visual questions (layout, interaction, density) and to empirical forks about behavior, timing, or approach. SKILL.md makes this a Non-negotiable: a fork you could settle by running something is prototyped instead of asked. With no decision to make, the work goes to Feature.

The steps:

  1. Scope the single decision the prototype exists to make.
  2. When the design space is open, gather prior art and summarize it as a moodboard of themes, palettes, and layouts so the user can pick directions. Skip this when the direction is already set.
  3. Build in an isolated scratch directory, away from production source. A visual decision uses vanilla HTML, CSS, and JavaScript or the lightest stack that renders the idea; a behavioral decision uses the smallest script that exercises the question. No production framework, tests, or abstractions.
  4. Put compared alternatives behind one switcher (buttons or a keypress), each variant labeled. The playbook calls this a cheap form of principle-exhaust-the-design-space.
  5. Verify on the matching surface: screenshot and drive each visual variant through the control skill, or log the timing and output for a behavioral one. Observation serves as the test here.
  6. Present alternatives, trade-offs, and a recommendation, then hand the chosen direction to Feature (or to architect for the shape).

This is the one playbook where the Laziness Protocol’s “smallest change” and the usual verification bar are inverted. Speed beats polish, code quality is irrelevant, and there is no planning; the rigor lies in choosing the right design cheaply. The agent may propose variations the user did not ask for, and it may discard one approach to try another.

The reply lists the variants, the evidence (screenshots or observed output), the trade-offs, a recommendation, and the scratch path, and it says plainly that the prototype is throwaway.

Session pickup: resume from the trail, do not redo it

Source: session-pickup.md

Session pickup takes over another agent’s in-flight work and identifies the exact resume point. The prior agent’s trail (a local transcript, a cloud-agent URL, or a pushed branch) is treated as authoritative input. The user guide separates it from the recall skill: use Session pickup when you want to resume one specific chat.

The steps:

  1. Locate the trail. A local transcript lives under the active workspace’s agent-transcripts/ directory, whose path the system prompt gives. Read the metadata overview and the last messages first, then scan back for decision points. A long transcript is parsed in a subagent so that only the reduced timeline reaches the main thread, per principle-guard-the-context-window.
  2. Reconstruct the operational state: branch and worktree, what already landed (git log, git diff against the base), open todos, and decisions already made.
  3. Compare what shipped with what was planned and name the resume point. Do not re-run the prior reproduction or repeat completed work.
  4. Route the remaining work to the matching playbook and pick a verdict: continue the execution, ship a finished recommendation, ratify or override an earlier conclusion, or write a postmortem of a failed run. The pickup playbook ends here, and the routed playbook owns the rest.
  5. Verify the inherited claims against the original goal on the real artifact, per principle-prove-it-works. A passing self-report from the prior agent is not proof.

Never glob across ~/.cursor/projects/*/. That crosses workspace boundaries and reads private chats from unrelated projects. Likewise, a “let me verify from scratch” pass is a warning sign: it treats an authoritative trail as untrustworthy.

The reply says where the prior agent stopped, what was inherited versus redone (ideally nothing), the resume point, and the outcome.

Pause safely: a clean stop with a resume note

Source: pause-safely.md

Pause safely stops work at a clean point and leaves a checkpoint from which a cold-start agent, one with none of the current context, can resume. It runs only on an explicit request to pause, for example before you go offline or restart Cursor. Phrases such as “keep going”, “going to bed, keep going”, or “don’t stop” never trigger it.

The steps:

  1. Halt at a safe boundary. Either complete the atomic step in progress or undo it, begin no new work, and cancel every nested subagent.
  2. Take no irreversible action for the sake of pausing. No new PR and no push, unless one was already out.
  3. Make the work durable by committing uncommitted edits as a single wip: commit on the current branch. If the tree is broken, say so in one line of the commit body.
  4. Write the resume note outside the context: intent, current activity, progress and what is verified, current state, next steps, key files, and gotchas. When context compaction is the trigger, write it to a file such as /tmp/<slug>-resume.md. If a show-me-your-work trail already exists, point to it instead of duplicating it.

The reply announces a pause and is not a final report. It says where the work stands in the loop, what is on disk versus only in the agent’s head (by path, without pasted diffs), the commits made and whether the tree is clean, and the first action on resume. The user guide pairs this playbook with Session pickup: a fresh chat resumes from the note through that playbook.

Playbooks: Autonomous Execution

This chapter covers 4 playbooks that keep work moving without waiting on a human. Autonomous run iterates toward a defined exit condition. Autopilot-full carries a whole queue of PRs to merged, and Autopilot-stack runs the same pipeline but stops before merging. Babysit shepherds a PR to merge-ready.

Several terms appear throughout:

  • Operator: the human who directs the run.
  • Trunk: the repository’s main branch.
  • Forge: the service that hosts the PRs. pstack uses the GitHub CLI (gh) by default and the Origin CLI (origin pr) when it can resolve the repository. Graphite (gt) is never required.
  • Head: the commit at the tip of a PR’s branch.

Autonomous run: define done, then drive to it

Source: autonomous-run.md

Autonomous run handles long or unattended work. The agent owns the exit condition: it defines “done” first, then keeps going until that condition holds. SKILL.md lists “Don’t stop”, “going to bed”, “run until done”, and “be fully autonomous” as session overrides that mean keep going. The user guide adds that work you will review after stepping away is routed through figure-it-out, which designs the run’s phases before any code.

The steps:

  1. Before the first iteration, state the exit condition as a predicate that can be checked, such as tests green, the repro fixed, all N PRs merged, or a pixel diff of zero.
  2. Choose a wake mechanism with Cursor’s built-in /loop command (not a pstack skill). If there is an event to watch (CI, a merge, a ref advancing), a watcher subagent wakes the agent on it, with a long time-based heartbeat as fallback. With no event, use a fixed heartbeat sized to when the result is worth re-checking.
  3. In each iteration, make the smallest change the evidence justifies, verify it against the predicate, commit it if it advanced, and discard it otherwise. Changes that only “might help” are reverted. Each unit is verified before the next, per principle-sequence-verifiable-units, instead of batching checks at the end.
  4. Handle discoveries that support the goal yourself: broken skills, related bugs, flaky verifiers, review noise, tooling failures, orphaned follow-ups, and fixable drift. Out-of-band fixes go into their own PR, and the agent returns to the predicate after each one.
  5. Record a checkpoint row every iteration with the show-me-your-work skill: what changed and whether the predicate moved.
  6. Stop when the predicate is met.

A plateau is not a reason to stop. The agent pivots its approach to push past it, surfaces a genuine dead end rather than spinning, and never relaxes the predicate to declare victory.

The agent does not park reversible work for the human or ask questions through AskQuestion. It surfaces only irreversible actions, product or preference calls that no experiment can settle, and real dead ends.

The reply gives the exit condition, the number of iterations, what landed, what was discarded, and the final state of the predicate.

Autopilot-full: a queue of PRs, carried to merged

Source: autopilot-full.md

Autopilot-full takes a queue of independent PRs from build to merge. One owner agent carries each PR, while the root agent that runs the playbook owns only the verdicts. Nothing merges until a swarm of verifiers that never wrote the code has proven the code that lands. The user guide’s example prompt is /poteto-mode full autopilot on this queue. each item is independent. i want them merged by morning.

One distinction runs through the whole playbook: a verdict covers one patch, and green CI covers one head. The git patch-id rule in the Shipping playbook can carry a verification lane’s result to a new head whose patch is unchanged, but every new head still needs its own green CI.

The steps:

  1. Check the operator’s gates first. The grant covers only the items in the queue. Items the operator claims as their own, and PRs outside the queue, stop at merge-ready. A request to describe the plan is not a go.
  2. Spawn one owner per PR, and keep its work where a replacement can find it. The forge is resolved once for the whole program. Each owner is a Cursor cloud agent that builds the change, opens its PR per Opening a PR, proves the change on the real artifact, babysits it to green per the Babysit playbook, and merges once steps 4 and 5 clear it. Where Babysit says to report a rebase, the owner rebases its own branch instead and publishes it with git push --force-with-lease.
  3. Run the owners in parallel off trunk and never stack them, so each PR can land on its own.
  4. Once the head is code-ready, run a full swarm on it a single time, as the swarm skill describes. The independent verifiers repeat the gates, audit the diff, and demonstrate the load-bearing behavior live with a control skill such as control-ui or control-cli (both from the cursor-team-kit plugin). A second full swarm is reserved for new behavior, a redesign, or a large new diff. After a rebase, a conflict resolution, or a minor fix, 1 verifier checks the new head; a change that only touches wording needs no verifier.
  5. Merge only what was verified and tested on the trunk it lands on. Green CI alone never authorizes a merge. Just before merging, the owner fetches trunk and asks whether its changes can affect the patch. It rebases and waits for CI when the landing code was never tested (a conflict, a file both sides changed, a change to which checks run). When trunk changed a caller or a dependency of the patch, it runs the patch’s checks on the merge result. If trunk would force a third rebase, it holds and reports to the root.
  6. Run the root layer. Anything that loosens a gate, such as a raised budget or a new allowlist entry, needs a verifier’s proof and then a fresh countersign from the root, because the owner is the party that wants green. A disabled or soft-failed check always comes out. An approval that the forge enforces is never given or bypassed, since no countersign covers it. On the operator’s go, the root arms /loop 1h to audit for drift and stuck agents until no delegated work remains.
  7. Stand down at once when the operator says stop. Each owner receives a zero-writes order, reports where it stands, and keeps its brief until released.

Several rules inside step 2 protect the work if an agent fails. The PR opens early so CI and bots run alongside the work. The code counts as ready only after /deslop (from cursor-team-kit) and the no-comments pass, followed by a rebase onto current trunk. Owners assume their VM may die: they push early, start a decision trail with show-me-your-work, and push each finished unit before starting the next. An owner force-pushes only its own branch, with --force-with-lease pinned to the SHA it last pushed or took over, and a push it did not make means stop and report to the root.

Blocking a PR requires a problem that can be demonstrated, namely a run that fails at the PR’s head or a line of documentation that the PR has made incorrect. If the problem already exists in the base (trunk, or the PR beneath it in a stack), it counts against the PR only when the PR copies it or makes it newly reachable. The blocking categories are limited to a bug that users would encounter, a gate that fails, and shipped documentation that is wrong; anything else is recorded as a follow-up.

On every hourly tick, the root reloads the playbook from trunk and assesses each agent by what it has actually changed, because status messages and summaries can conceal a child that has stalled. An agent counts as stuck if it hits errors, cannot begin a turn, or has produced nothing new after its expected runtime; such an agent is replaced immediately. An agent that is waiting for the root or the operator is a different case: it is not stuck and simply receives a reply.

The reply follows the ketchup skill: each PR’s state and verdict, what merged, countersigns and their reasons, open operator gates, and parked follow-ups, with links to each PR and trail.

Autopilot-stack: autopilot without the merge

Source: autopilot-stack.md

Autopilot-stack runs the Autopilot-full pipeline but stops once each PR is verified and green, then hands the PRs to the operator to review and land. Choose it when you want autonomous building and verification but your own eyes on the work before anything merges. The user guide’s example is /poteto-mode autopilot these five changes, but don't merge. i'll land them in the morning.

The playbook changes 2 parts of Autopilot-full:

  1. Step 5 (the owner’s merge) is replaced by a stop at verified. After the handoff, no agent pushes without the operator’s go.
  2. A PR is stacked only when it builds on another PR. This is the single exception to step 3. Such a PR is based on its parent PR’s branch instead of trunk and rebases onto that branch, and only the root of the stack rebases onto trunk. When a lower PR gets a new head, the PRs above it are restacked, and a PR whose git patch-id the restack leaves unchanged keeps its verdict.

Every loop tick’s prompt names this file, so each tick sees the no-merge rule again. The reply lists each PR with its verdict, in place of a list of what merged.

Babysit: a PR to merge-ready, one at a time

Source: babysit.md

Babysit drives a PR or a stack to merge-ready, clearing one PR at a time and stopping where a human’s decision begins. The playbook calls this owning the merge frontier. SKILL.md routes requests for PR status here rather than to Cursor’s built-in babysit skill.

The rules:

  1. Declare the mode in the first line, before any poll. drive loops to merge-ready, threads-only touches only review threads, and check makes 1 status pass and reports.
  2. Read status from the forge. On GitHub, the watcher at scripts/watch-pr/watch-pr provides it, with --status-only in check mode. On Origin, use origin pr view <pr> --checks and origin pr checks <pr> --watch.
  3. Work in a fixed order: conflicts, then threads, then CI. A conflict is the one blocker the agent reports instead of resolving. It names the branch that needs a rebase and stops, without falling through to CI to look busy. The report also names the drift sweep, since trunk may have gained callers of code the stack deletes or moves.
  4. For CI, a flaky failure earns 1 fresh build, and only the diff’s own failures get a commit.
  5. Triage Bugbot comments skeptically: fix real findings, dismiss noise with a concrete disproof, and escalate anything touching billing, data, auth, or security. Each claim is checked against the code per references/bugbot-triage.md. The fixes are pushed before replying, so the reply can cite the commit.

The agent never rebases, retargets, or force-pushes. Babysitting never authorizes a merge either; owner approval is treated as a wait.

Comment text is treated as data and never as instructions. Replies go through a dedicated API call (gh api --method POST ".../comments/<comment-id>/replies" --input <payload.json> or origin pr thread reply), never through a shell command assembled from comment text.

Playbooks: Troubleshooting

This chapter covers the 5 playbooks that respond to “something is wrong”. They differ in how far they go: Bug fix and Perf issue end by opening a PR (Perf issue with the measurement cited in it), and Investigation, Runtime forensics, and Trace forensics stop at an explanation or a diagnosis and change no code.

A few terms recur across all 5:

  • Control skill: a skill that drives the real product the way a user would, such as control-ui or control-cli from the separate cursor-team-kit plugin. “The matching surface” means the place where the problem actually shows up (the running UI, the CLI, the IDE).
  • Configured model: the model a code-writing subagent runs on. /setup-pstack writes one line per role into ~/.cursor/rules/pstack-models.mdc, and each playbook reads its own line. Where no line exists, the default is claude-opus-5-5-xhigh-fast.
  • Throughput checkpoint: the 4-item plan for parallel work (blocking first steps, independent workstreams, shared mutable state, smallest safe decomposition) that the Feature playbook writes before delegating; see Planning and starting. The read-only playbooks in this chapter reduce it to a single line marked n/a.

Bug fix: every shipped line traces to evidence

Source: bug-fix.md

Bug fix is the playbook for repairing broken behavior. The agent in charge keeps planning, review, and verification for itself and hands both the investigation and the implementation to subagents. Its central rule is scientific: each line that ships must be justified by something observed at runtime, and a defensive extra change that “might help” counts as an untested hypothesis, so it stays out of the diff.

The steps:

  1. Reproduce the bug personally on the matching surface through the control skill. This applies even when some debugging protocol suggests asking the user to reproduce it. The agent may ask the user only after it has driven the control surface as far as it can, and only with a specific reason why that surface cannot reach the target. If the bug does not appear on demand, the agent synthesizes the trigger, tightens the conditions, or adds instrumentation until it does.
  2. Binary-search the cause. The agent lists candidate hypotheses and eliminates them until one survives. A trace of the affected subsystem and the why skill (for regression history) supply the first candidates. Each round picks the split that removes the largest share of the remaining problem space, gathers runtime evidence, and discards what the evidence rules out. Where program state is unclear, the agent adds logging and reads it while the code runs. A long hunt can be driven with Cursor’s /loop command. The surviving mechanism must be confirmed with runtime evidence before any design work starts.
  3. Plan the fix. A fix that crosses a function boundary goes through the architect skill first. Implementation goes to a subagent on the configured bug-fix model, with a precisely stated scope.
  4. Verify on the same surface. The original reproduction must now pass. A result that is “inconclusive”, or one taken on a different surface, does not count as a pass and must be reported as such. Unit tests demonstrate how individual branches behave; they cannot show that the bug is absent.
  5. Order the commits so that the failing reproduction appears in history before the fix. When the bug has a cheap local test, the tdd skill supplies the failing-test-first rhythm; when a test would be expensive or integration-heavy, the agent skips it. The playbook calls this the canonical case of the principle-sequence-verifiable-units skill.
  6. Run Opening a PR (see Shipping).

When evidence refutes a hypothesis, the agent reverts whatever that hypothesis motivated. Only the smallest change the evidence supports ships.

The final reply states what was broken, the root cause, the fix, and how it was verified. It includes the reproduction output twice, failing and then passing, pasted verbatim.

Investigation: answer the question, change nothing

Source: investigation.md

Investigation handles requests for understanding or for a decision, and it is strictly read-only. The deliverable is either an explanation with citations into the code or, when the user must choose between alternatives, a recommendation. The agent owns the answer itself.

The steps:

  1. Trace the code that the question concerns. Questions about motivation (“why is it built this way?”) also go through the why skill.
  2. Record the throughput checkpoint as one line: throughput checkpoint: n/a, read-only investigation.
  3. Write the output. An explanation uses 5 fixed sections: Overview, Key Concepts, How It Works, Where Things Live, and Gotchas. A decision request gets a recommendation backed by a trade-off table.
  4. Run the unslop skill over the reply before sending it.

This playbook opens no PR, starts no babysit, and does not call architect. If the investigation turns out to be the first stage of a code change, the agent stops, returns to the user, and re-routes the work to Bug fix or Feature.

When the user asks “are we sure?”, the reply must contain the agent’s actual judgment and its reasons. If the premise of the question is wrong, the agent says so, in line with the candor rule in the Autonomy section of poteto-mode.

Perf issue: tie every fix to a measurement

Source: perf-issue.md

Perf issue treats a one-off performance problem as a measurement story that the agent owns. Every proposed fix is linked to a number, and reading the source is never accepted as a substitute for running it.

The steps:

  1. Capture a baseline trace through the matching control skill. The baseline, and every later number, is vetted with the benchmark-checklist skill, which asks what limits the number and whether the work really ran inside the timed region.

  2. Trace the code to ground hypotheses. The agent may not claim a performance ceiling before it has run the code. Candidate fixes follow the 7 performance mantras, quoted here from the playbook, cheapest first. The search stops as soon as an earlier mantra reaches the target:

    OrderMantra
    1“Don’t do it.” (Stop work whose result nothing uses, instead of making it cheaper.)
    2“Do it, but don’t do it again.”
    3“Do it less.”
    4“Do it later.”
    5“Do it when they’re not looking.”
    6“Do it concurrently.”
    7“Do it cheaper.”
  3. Plan the fix from the trace. A boundary-crossing fix goes through architect first. A subagent on the configured perf-issue model implements it, the agent reviews the diff, and then captures a post-fix trace. Following principle-sequence-verifiable-units, each attempt is verified before the next one begins.

  4. Parse and compare the artifacts, for example by loading JSON traces into sqlite and diffing them. An inconclusive result or a measurement on the wrong surface is flagged and never counted as a pass.

  5. Cite the measurement in the PR.

  6. Run Opening a PR.

For sustained improvement against a metric, as opposed to a single fix, the playbook points to Hillclimb (covered in Shipping).

The reply gives the baseline number, the post-fix number, the delta, and the path to the artifacts.

Runtime forensics: instrument the live process

Source: runtime-forensics.md

Runtime forensics applies when the symptom is happening now, in a process that is still running. The agent owns a diagnosis, and it is expected to gather live signals from that process instead of building a theory from the source. The deliverable is a cited diagnosis; a fix is out of scope unless the user asks for one.

The steps:

  1. Capture the live signal on the matching surface through the control skill. The kind of capture depends on the symptom: a CPU profile for a process that spins, a heap snapshot for a leak, a CDP (Chrome DevTools Protocol) trace for a visual glitch. The point is a real artifact on disk.
  2. Reduce the artifact to the decisive evidence: the function on the hot path, the retainer chain that keeps a leaked object reachable from a GC root, or a loop that fires without any input. Large artifacts are parsed in a subagent, per principle-guard-the-context-window, so that only the reduced finding enters the main thread.
  3. Prove the mechanism before trusting it. Cheap confirmation methods include injecting instrumentation into the running process through CDP eval, or hot-patching the live code without a reload.
  4. Map the finding to source: the file, the symbol, and the line that allocates memory or schedules the work.
  5. Record the throughput checkpoint as one line: throughput checkpoint: n/a, read-only forensics.

The reply lists the captured signal, the reduced finding, how the mechanism was proved, the source location, and the artifact paths. Once the cause is known, the work is handed to Bug fix or Perf issue.

Trace forensics: diagnose from an existing capture

Source: trace-forensics.md

Trace forensics is the counterpart of Runtime forensics for the case where the capture already exists: a cpuprofile, a .json.gz trace, a spindump, or a heap snapshot. The playbook treats the artifact as a fixed dataset to be read, so nothing is re-run. Tooling stays generic (a DevTools or trace parser, a text editor for a spindump, ordinary heap tooling) instead of being built anew for each format.

The steps:

  1. Identify the format and open it with a suitable tool. Large artifacts are parsed in a subagent, again per principle-guard-the-context-window.
  2. Make the artifact queryable before reading it. The usual move is to dump it into sqlite with one row per sample, frame, or node.
  3. Narrow to the cause. With CPU time, query the frames holding the largest share of time and descend the call tree along the hot path. With a leak, trace the retainer chain from the leaked object up to a GC root. With a spindump, locate the thread that is either stuck on the CPU or blocked, along with the reason it is waiting.
  4. Attribute to source using the symbols in the artifact itself. A hot frame without a file, symbol, and line is not yet a diagnosis; the agent either resolves the symbols or states plainly that the artifact lacks them.
  5. Confirm with a paired capture if one exists, by diffing the before and after artifacts. Without a pair, the result is presented as the strongest hypothesis the artifact supports, and it is never called a confirmed cause.
  6. Hand back a cited diagnosis without a fix, unless one was requested, and route to Bug fix or Perf issue once the cause is known. The throughput checkpoint is the same one-line n/a as in Runtime forensics.

The reply names the artifact and its format, the reduced finding, the source location, the artifact paths, and whether a paired capture confirmed the result.

Playbooks: Shipping

This chapter covers 4 playbooks that move finished work toward trunk or measure whether it is actually better. Opening a PR defines how a pull request is written and opened. Shipping lands a stack of verified PRs. Hillclimb is a loop that improves one metric, and Eval compares variants of a skill or prompt in a blinded experiment.

2 terms appear throughout:

  • Forge: the service that hosts the PRs. pstack uses the GitHub CLI (gh) by default and switches to the Origin CLI (origin) when it is installed and can resolve the repository.
  • Stack: a chain of PRs in which each PR’s base branch is the branch of the PR below it, so the bottom PR targets trunk.

Opening a PR: the shared closing step

Source: opening-a-pr.md

Opening a PR describes itself as “invoked at the end of every other playbook”. In practice it is the last step of the playbooks that change code, such as Feature, Bug fix, Perf issue, Refactoring, Hillclimb, Visual parity, and Authoring a skill; the read-only playbooks (Investigation and the 2 forensics playbooks) never reach it. Its job is to make every PR look the same regardless of which playbook produced it.

The rules, in the order they apply:

  1. Isolate the work. Work happens in a git worktree created from trunk, and unrelated changes stay out of it. Before opening, the commits are rebased into small units that could each land on their own.

  2. Clean the diff. Before committing, the agent runs /deslop from the cursor-team-kit plugin over the diff.

  3. Write the title as type(scope): subject. If a real symbol carries the change, the subject names it.

  4. Write the body as a one-minute briefing of fewer than 40 lines. It uses these ## headings in this order and omits any that would be empty:

    1. ## Why, which opens with the goal (a rule from the Non-negotiables in poteto-mode).
    2. ## What changed
    3. ## Scope
    4. ## Tradeoffs, limited to rejected alternatives that a reviewer would otherwise ask about.
    5. ## Blast Radius
    6. ## Verification
  5. Stack follow-ups by base branch instead of growing one branch.

  6. Open the PR ready for review. The agent uses the run’s own PR tool with draft: false. Without such a tool, it uses gh pr create without --draft, or origin pr create --status open when the Origin CLI resolves the repository.

Opening a PR does not start a babysit. Watching the PR until it is merge-ready belongs to the Babysit playbook (see Autonomous execution).

Shipping: land only what an independent agent verified

Source: shipping.md

Shipping is the fixed route for landing a green stack: the Non-negotiables in poteto-mode send “landing a green stack” here. The agent owns what lands. It verifies each PR independently, lands only the verified part of the stack from the bottom, and otherwise leaves the stack untouched while it merges.

Some vocabulary first:

  • Verdict: the result a verifier posts on a PR, one of PASS, PASS+NOTES, or FAIL.
  • Run: the contiguous sequence of verified PRs starting at the lowest unmerged PR.
  • Ceiling: the top PR of that run.

The steps:

  1. Resolve the forge and verify each PR. The default tool is gh. When command -v origin succeeds and Origin can resolve the repository, all PR operations use origin pr; if not, the agent keeps using gh and logs that it fell back. Graphite (gt) is never a requirement. Every PR receives a single verifier: a Cursor cloud agent that exercises the change the way a user would through the matching control skill (for example control-ui or control-cli from cursor-team-kit), compares parent with head, and posts its verdict on the PR.
  2. Land only the contiguous verified run. Starting from the lowest unmerged PR, the agent walks upward and stops at the first PR that lacks PASS or PASS+NOTES. A verified PR that sits above an unverified one has to wait, because it depends on the code below it. There is one exception: a PR whose branch neither contains nor needs that code can be moved onto trunk and landed alone, but only after it receives a fresh verdict, since its earlier verdict was produced with the other code underneath.
  3. Check that each verdict still describes the code. A verdict applies to a patch, and a chain rebase gives every PR above it a new SHA without failing any check. Before trusting an older verdict, the agent compares git patch-id at the verdict SHA with the current head. If the patches differ only in tests, docs, or lint configuration, the result of a lane (the playbook’s word for one verification check run against the PR) can stand, provided what the lane ran builds identically at both SHAs apart from noise. The playbook defines noise as a difference that also appears between 2 builds of the verdict SHA, or an embedded commit SHA, and each kind of noise must be reported with its files. The new change itself still needs fresh checks and a review. A lane with no build output, such as a dev server, cannot demonstrate identical builds, so it is rerun.
  4. Land bottom-up, one PR at a time. The PR the agent merges is always the lowest one in the run that has not merged yet, using origin pr merge <pr> or gh pr merge <pr> --squash. Merging in any other order fails: on Origin, the plain command merges every PR beneath the named one as well, and on GitHub, a PR still based on its parent’s branch lands in that branch rather than in trunk. Afterwards the agent reads the PR again (origin pr view <pr> or gh pr view <pr> --json state,mergedAt,baseRefName). This check is needed because a merge command may report success when a merge queue has merely queued the PR, and because a requested auto-merge has not yet merged anything. A PR has landed when it appears as merged with trunk as its base. Following each merge, the agent retargets the next PR to trunk, moves its patch onto the merge result, and pushes the branch with --force-with-lease; whether its verdict still holds is then decided by the patch-id rule from step 3. The agent arms --auto only on a PR whose verdict covers its current head.
  5. Leave the stack alone while it lands. The retargeting in step 4 is the only permitted change to any branch or base. On GitHub, the agent watches with the bundled watch-pr script, run as watch-pr --queued-stack under /loop with the run’s PR numbers in --stack-prs (bottom to top, the same list on every restart), until it reports COMPLETE at the ceiling. On Origin, it re-reads the PR with origin pr view <pr> --checks each time origin pr checks <pr> --watch returns. A base that moves to trunk after its parent merges is expected. If a merge stalls, the agent finds the reason before changing anything.
  6. Stop at the ceiling. Landing more requires new verdicts, which means a new pass starting from step 1.

2 rules explain why the verification step cannot be skipped. A verdict from the agent that wrote the code does not count, since an author tends to confirm what it intended to build. Green CI and an approving bot review do not count either, because neither runs the change the way a user would.

The reply reports the verified run and its ceiling, each PR’s verdict and which agent produced it, what landed and how that was confirmed, and what the next gap in the stack needs.

Hillclimb: one change, one measurement, keep or revert

Source: hillclimb.md

Hillclimb is for sustained, iterative improvement of a single measurable quantity toward a target. A one-off fix belongs to Bug fix or Perf issue (see Troubleshooting); Hillclimb is the loop. The agent owns the metric and the integrity of the experiment, supervises and reviews, and delegates each attempt to a subagent on the configured hillclimb model (default claude-opus-5-5-xhigh-fast, set in ~/.cursor/rules/pstack-models.mdc by /setup-pstack).

Its core discipline is a single rule: one change, one measurement, then keep or revert. Untested changes are never stacked, and a win is never claimed from reading code, per principle-prove-it-works.

The steps:

  1. Understand the workload before choosing a metric. The agent traces the target, identifies the realistic dimensions that could shift the result (data size, history, state, concurrency), and selects a case that reproduces what the user complained about. When no case reproduces it, the agent repairs the reproduction instead of starting to hill-climb. Next, it settles on one metric, the direction that counts as an improvement, and a checkable stop predicate. The predicate combines a target with a minimum number of attempts, so an early lucky win cannot end the run; the playbook’s example is “at least 50% better than baseline and at least 10 iterations”. If the user has supplied numbers, those are used; if not, they are agreed with the user.
  2. Build the measurement rig, show that it is sensitive, and then freeze it (principle-build-the-lever). When realistic workloads are contrasted, the target case has to reproduce the symptom and the easier cases have to separate as expected; otherwise the workload or the metric gets revised. The rig passes through benchmark-checklist and has to print both its error count and a count of the work it did. After the freeze, one repeatable command produces the metric, with enough samples to rise above noise (a median of N runs). Before anything changes, the agent records the baseline and a green run of the regression gate, that is, the tests that must keep passing.
  3. Open a decision log through the show-me-your-work skill: a decision.tsv file, kept out of the tree (gitignored), with one row per attempt and the columns id, hypothesis, change, before, after, delta, tests, verdict (kept or reverted), and note. The agent reads it before each attempt.
  4. Ground every hypothesis in the architecture from step 1, so that it names a specific mechanism. The playbook contrasts “defer X off the boot path because it blocks first paint” with the vague “try memoizing something”. For a performance metric, hypotheses follow the order of the Perf issue mantras, but without the Perf issue rule that stops at the first mantra that meets the target.
  5. Loop, one hypothesis per iteration. A subagent makes the change within a tight scope while the agent reviews the diff, per principle-guard-the-context-window. Independent hypotheses can run in parallel subagents, each in its own worktree, per principle-separate-before-serializing-shared-state. Each attempt is measured before and after with the frozen rig, and the regression gate runs. A change is accepted only when the metric moves beyond noise and the gate stays green; anything else is reverted in full. Each accepted fix becomes one commit that stages only the changed files (git add <files>, never -A), and every attempt gets a log row whatever the outcome. If the run is unattended, it borrows only the wake mechanism from the Autonomous run playbook (see Autonomous execution), and keeps its own stop rule.
  6. Push past the first plateau. After several rejections in a row, the agent changes the category of idea, combines near-misses, re-reads the source, or tries something bolder. Correctness and simplicity still outrank the number: a win that breaks behavior is reverted, and a simplification that holds the number is kept, per principle-laziness-protocol.
  7. Stop once the predicate holds, or once the ideas that remain are marginal and would cost more than they return. The agent may not loosen the predicate to claim success, and it may not give up while cheap hypotheses are still untested. When it is stuck, it reports that rather than repeating attempts.
  8. Run Opening a PR, with the accepted commits stacked in the order they landed.

The reply gives the metric and target, the change from baseline to final with the percentage delta, the number of iterations (kept versus reverted), one line per accepted fix, the decision.tsv path, and the best idea to try next.

Eval: compare variants in a blinded experiment

Source: eval.md

Eval answers whether a variant (a changed skill, prompt, or similar) actually behaves better, using an experiment in which the agents under test do not know they are being tested. The agent owns the experimental design: it plans, blinds, runs, and synthesizes. 2 roles take part. Candidates are agents that perform the task with the variant in place, and the judge is a separate agent that scores their outputs.

The blinding rules are non-negotiable:

  • No directory, file, or prompt that a candidate sees contains the words eval, test, judge, experiment, rubric, score, compare, benchmark, candidate, or arena.
  • The candidate prompt reads like an organic user request and states the goal only.
  • Candidates are never asked to list the skills, principles, or files they applied. They may be asked for design notes in general. Chain-following, meaning whether a candidate actually read and applied the skills and principles the variant points it to, is graded from the shape of the code.
  • Directory names and slugs are sanitized into project-like names a user might choose.
  • Candidates are not told that other candidates exist.
  • The judge may know that it is judging, but it sees outputs only under sanitized labels, never by model name.
  • When 2 variants are compared, a single judge scores both sets in one pass on one scale, without knowing which set came from which variant.

The steps:

  1. Frame the experiment. State the variant under test and the behavior that counts as success, then write a rubric of 3 to 6 concrete criteria for the judge only.
  2. Prepare sanitized environments: one working directory per candidate with the variant installed, plus whatever context an organic task would have, such as a project skeleton and the skills the candidate would naturally read.
  3. Write one organic prompt, phrased the way a user would type it, with nothing that hints at what is being measured.
  4. Spawn N candidates in parallel on different models, following Phase B of the arena skill. All receive the same prompt, each in its own directory. An agent that only dispatches, polls, or packages results runs on claude-opus-5-5-medium-fast.
  5. Spawn one blinded judge from a different model family, following Phase C of arena. It sees the rubric and the outputs under sanitized labels.
  6. Verify chain-following from transcripts. The agent reads each candidate’s local transcript under the active workspace’s agent-transcripts/ directory and checks which files the candidate actually opened. It must not glob across ~/.cursor/projects/*/, because that would cross workspace boundaries and read private chats from unrelated projects. The grade combines the files really read with the shape of the code, and ignores what the candidate claims about itself.
  7. Read every candidate output end to end and compare it with the judge’s verdict. A disagreement indicates either a biased model or an ambiguous rubric. The agent then synthesizes a conclusion.

The reply covers the variant under test, the rubric, notes on each candidate, the judge’s verdict, the agent’s own synthesis, and a recommendation on whether to promote the variant.

Playbooks: Improvement and Cleanup

This chapter covers 4 playbooks that work on something that already exists. Refactoring changes structure without changing behavior, Visual parity migrates UI without changing a single pixel, Worktree cleanup reclaims disk space from accumulated worktrees and simulators, and Authoring a skill creates or revises a skill.

Several steps below cite principle skills: the principle-* skills bundled with pstack, each of which states one rule and when it applies. The chapters from Principles: An Overview onward describe them. Code-writing subagents run on a configured model that /setup-pstack records per role in ~/.cursor/rules/pstack-models.mdc (default claude-opus-5-5-xhigh-fast).

Refactoring: change the structure, hold the behavior

Source: refactoring.md

Refactoring changes how code is organized while its observable behavior stays fixed. The agent owns the behavior contract. The playbook sets itself apart from Feature, which adds behavior, and from Bug fix, which corrects it.

Its scope is a focused to medium-sized change. Large or cross-cutting structural work goes to the figure-it-out skill. If the cleanup uncovers a missing feature or a real bug, the agent splits that out and ships the structural change first, against the pinned contract. A redesign is permitted, provided the agent names it as one and routes it to Feature.

The steps:

  1. Pin the behavior contract. The agent traces the affected subsystem to learn what it promises, then writes a characterization test, a snapshot, or an equivalence check that captures current behavior before anything moves. Where coverage is missing, the pin is written first. A type check or lint run does not qualify as a pin.
  2. Name the missing structure, per principle-model-the-domain. Plain code whose shape is already clear and local should stay as it is. A reshape has to remove branches or invalid states; one that only adds indirection does not qualify.
  3. Name the target shape, meaning the module layout, types, and call graph that the code would have if someone wrote it from scratch today (principle-foundational-thinking, principle-redesign-from-first-principles). When that target reaches across a function boundary, the architect skill fixes the shape before any code is moved.
  4. Subtract before adding. Dead code, wrappers with a single caller, redundant validators, and orphaned references are removed before the new shape is introduced (principle-subtract-before-you-add). The smallest change that reaches the target ships (principle-laziness-protocol), and speculative cleanup that “might help” is reverted.
  5. Move in small steps that preserve behavior, keeping the pin green after each one. An API reshape migrates every caller and deletes the old API in the same wave (principle-migrate-callers-then-delete-legacy-apis), so no compatibility shims or parallel old and new paths remain. Every rename is checked against the actual files, since renames tend to miss usages inside strings, prose, and back-references. Mechanical edits go to a subagent on the configured refactoring model, with a precise scope: file paths, the names being moved, and the behavior to hold.
  6. Show on the real artifact that the behavior has not changed; a successful compile does not count as proof (principle-prove-it-works). For a larger reshape, add an equivalence check: for example, a script that compares the old and new outputs, a recorded baseline replayed against the new code, or a smoke run through a control skill on the matching surface.
  7. Confirm the change earns its place. Success is measured as reduced reader load (principle-minimize-reader-load), and a diff that lowers reader load nowhere is reverted.
  8. Rebase into small, ordered commits: subtraction first, then the reshape, then any follow-up cleanup, shaped with principle-sequence-verifiable-units so each slice stays green. Then the agent runs Opening a PR (see Shipping).

The reply describes the structure that changed, the pin it was held against, the equivalence proof, the change in reader load, and what shipped versus what was reverted. It should report no new behavior.

Visual parity: the baseline is the specification

Source: visual-parity.md

Visual parity governs UI migrations that must leave the rendered result pixel-identical, for example when one implementation replaces another. The agent owns pixel-exact equivalence. The baseline screenshots act as the specification and are never modified, and equivalence is decided by an image diff instead of by eye.

The steps:

  1. Establish the baseline before migrating anything: a visual regression suite that screenshots the current component in each of its states, plus the target implementation when 2 implementations must match. Without a baseline there can be no parity claim, so this is a blocking prerequisite and cannot be deferred to later work.
  2. State and hold the anti-shortcut clauses. The agent may not modify the screenshot suite, tamper with the baseline, or restructure a component merely to make a diff pass. If the baseline itself looks wrong, it stops and asks instead of editing it.
  3. Migrate one component at a time. Work can run in parallel across worktrees with one owner per component (principle-separate-before-serializing-shared-state), but shared primitives migrate first, as a blocking phase.
  4. Verify each component against its baseline with an image diff on the matching surface through the control skill. Any nonzero diff is a failure: the agent investigates the pixel delta and repeats per component under Cursor’s /loop command until the diff reaches zero.
  5. Run Opening a PR, either per component or per batch that is safe to ship together.

The reply lists the components migrated, the diff result for each, the location of the baseline suite, and the work that remains.

Worktree cleanup: delete user state only behind explicit gates

Source: worktree-cleanup.md

Worktree cleanup (titled “Worktree and simulator cleanup” in the source) audits accumulated git worktrees and simulators and deletes only what the evidence shows to be safe. The playbook notes that it is the one playbook that deletes user state without a code review to catch a mistake, so its gates take the place of that review.

The steps:

  1. Snapshot and audit. The agent first notes the output of df -h /, then runs the bundled worktree-audit.sh as scripts/worktree-audit.sh [-b <pr-base-ref>] [repo-path] (principle-build-the-lever). By default the script checks merge state against origin/HEAD; if PRs target a different branch, pass -b origin/<branch>. Worktree paths come from git worktree list rather than from paths typed by hand, since a typed path like myrepo-worktrees/x would overlook a worktree kept under .cursor/worktrees/myrepo/x (principle-encode-lessons-in-structure). For every worktree the script reports size, age, merge state, uncommitted work, PR state, and the latest chat that touched it, and it proposes a bucket. Because scanning transcripts takes a long time, the script runs in the background.
  2. Treat the bucket as advice. The authoritative evidence is the set of pinned and active chats, obtained from the user or the sidebar and checked against every candidate (principle-prove-it-works). When the bucket and the pinned set disagree, the pinned set wins; the playbook records a case where the script marked as safe a worktree the user had pinned.
  3. Verify usage before deleting. For every row flagged verify-recent-chat, and for any row that looks uncertain, the agent dispatches subagents to read the transcripts and report back whether the chat is pinned or still active and which worktrees it uses (principle-guard-the-context-window, because transcripts are large). Through background subagents, a pinned chat may have created arena or reproduction trees in sibling worktrees; these are in use even when their names are never shown in the sidebar.
  4. Pause before irreversible loss. wip:N means N tracked, uncommitted edits: the agent shows the diff and waits for a decision, because a clean worktree can be recreated from its branch while uncommitted work cannot. scratch:N means untracked throwaway files, which may be dropped once the agent names them. Following the Autonomy rules of poteto-mode, a worktree that is clean, merged, and unused proceeds without asking, while wip and in-use worktrees pause.
  5. Prune the confirmed set. For each path the agent runs git worktree remove --force <path>; if the directory survives because of ignored build artifacts, it removes it with rm -rf and then runs git worktree prune. Branch refs remain, so no commits are lost. It confirms the result with df -h / and a fresh listing.
  6. Reclaim space elsewhere. Simulators are usually the next largest source: xcrun simctl --set testing delete all removes XCTestDevices clones, xcrun simctl delete unavailable removes unavailable devices, and xcrun simctl runtime list followed by runtime delete <id> removes old runtimes. Further candidates include Xcode DerivedData and iOS DeviceSupport, ~/Library/Application Support/Cursor (notably state.vscdb.backup and snapshots/roots/<root>, where a root named after a folder opened as a workspace can grow very large), and package caches for pnpm, uv, brew, and yarn. Caches the user has asked to keep are left alone.

The reply shows df -h / before and after with the space reclaimed, lists the pruned worktrees, and gives a one-line reason for each worktree held back (which chat uses it, or that it holds uncommitted work).

Authoring a skill: own the skill’s voice

Source: authoring-a-skill.md

Authoring a skill (titled “Authoring or modifying a skill” in the source) covers writing a new skill or revising an existing one. The agent owns the skill’s voice.

The steps:

  1. Write the skill with create-skill, Cursor’s built-in skill for authoring SKILL.md files.
  2. Validate it: the frontmatter has name and description, every referenced file exists, and every link to another skill resolves.
  3. Add test cases if the skill is structural; skip them if its effect is subjective.
  4. Run Opening a PR.

The playbook also sets a writing style for skills:

  • When in doubt, delete. Only prose that changes a decision stays.
  • State the instruction directly and leave out the justification, unless the rule would be confusing without one.
  • Match the tone to the skill’s scope.
  • Point at structural sources such as types, READMEs, and configuration, per principle-encode-lessons-in-structure, and delegate to other skills by path instead of restating them.

The playbook adds one more duty: when a workflow keeps recurring without being captured anywhere, the agent should propose a new skill for it.

The reply summarizes the skill, its key design decisions, and the validation results.

Skills Overview

What a skill is

A pstack skill is a single Markdown file named SKILL.md, placed in its own folder under skills/. It contains instructions, not code. A short header (the frontmatter) gives the skill’s name and a description of when to use it; the body sets out the steps, the criteria for judging the result, and the shape of the reply. When the agent loads a skill, it follows those instructions.

Skills vary considerably in size. /in-your-own-words is a single sentence, whereas /arena and /statechart run to several phases, and /statechart also ships helper scripts and a reference file next to its SKILL.md. What the larger skills have in common is that they define where to stop and what counts as evidence, so that a careful way of working can be repeated rather than improvised.

pstack 0.15.44 contains 58 skills. 24 of them are principles (folders named principle-*), and the remaining 34 are the working skills this part of the book describes.

How skills are invoked

Through /poteto-mode

The usual entry point is /poteto-mode. It reads your request, matches it to one of its playbooks (a predefined sequence of steps for a kind of task), opens a todo list whose first items are that playbook’s steps, and calls other skills as the steps require them. According to the README, the skills it routes to on its own include why, architect, arena, swarm, interrogate, unslop, no-comments, technical-writing, tdd, and the principles. You therefore do not need to memorize individual skills to benefit from them. See /poteto-mode and Playbooks Overview.

By typing /name yourself

You can also call any skill directly as a slash command, for example /how do we cancel runs?. In Claude Code, plugin commands carry a prefix, so /poteto-mode becomes /pstack:poteto-mode.

Every working skill except /setup-pstack sets disable-model-invocation: true in its frontmatter. In practice this means the agent does not start such a skill on its own initiative because its description happens to match the conversation; the skill runs when you type it or when another skill, such as /poteto-mode, names it as a step. The README states this explicitly for /poteto-help, /in-your-own-words, and /sharpen: each “runs only when you type” it.

Principles: same format, different role

The 24 principle-* folders use the same file format, but each one states a rule for judgment rather than a procedure. /poteto-mode contains an inline index of all 24 and reads it when a task starts. The standalone files exist so that other skills can cite a principle by name and so that the index can point to the full text of each rule. The index sorts them into 5 groups:

GroupCountExamples
Core10Laziness Protocol, Foundational Thinking, Attack the Premise, Subtract Before You Add
Architecture6Model the Domain, Boundary Discipline, Type System Discipline
Verification5Prove It Works, Fix Root Causes, Sequence Work into Verifiable Units
Delegation2Guard the Context Window, Never Block on the Human
Meta1Encode Lessons in Structure

The Principles Overview covers them in detail.

How skills depend on each other

Many skills are self-contained, but several call others as building blocks. The main dependencies, taken from the SKILL.md files themselves, are these:

  • /architect hands a large or contested design to /arena instead of sketching alone.
  • /interrogate reuses part of the /arena procedure (choosing runners and fanning out in parallel) and states the intent with /in-your-own-words.
  • /blast-radius presents itself as a companion to /how and /why, runs as an /arena for a large change, and writes its result through /unslop.
  • /figure-it-out uses /architect (and therefore /arena) for one-way design decisions and /show-me-your-work for its decision log.
  • /teach runs /how and /why and weaves their findings into one explanation.
  • /ketchup-video builds on /ketchup, and each verification skill generator is paired with a maintainer (/create-verification-skill with /maintain-verification-skill, /create-formal-verification-skill with /maintain-formal-verification-skill).
  • /recall, /automate-me, /show-me-your-work, and /technical-writing all pass their prose through /unslop.

Skills with no such references, for example /unslop, /why, /how, /tdd, and /bro, work on their own.

The 34 working skills by chapter

This book assigns each working skill to exactly one of six reference chapters.

/poteto-mode is listed with the skills about pstack itself, next to /poteto-help and /setup-pstack, because it is the plugin’s own entry point. It is large enough to have a chapter of its own, /poteto-mode, which is where it is described in full.

How to use the reference chapters

Each reference chapter describes its skills from the same four angles:

  • what the skill does;
  • when to use it;
  • how it proceeds, summarized from its SKILL.md;
  • caveats and limits.

There are 3 sensible ways to read them:

  1. Start with /poteto-mode and the playbook chapters to see how the whole system runs. At that stage it is enough to know that the individual skills exist.
  2. Read in advance only the chapters that match situations you meet often, such as reviewing, investigating, or designing.
  3. When a skill surprises you in practice, return to its section and check the caveats.

If you are not sure which skill fits a task, ask /poteto-help before searching these chapters. It finds out what you are trying to do, answers that part, and gives you a prompt you can send; it does not start the work itself. The chapter Choosing Between Similar Skills compares skills whose names or purposes overlap.

Understanding and Investigation

The skills in this chapter build understanding before anyone edits code. Editing code that no one has traced is a common way for subtle regressions to reach production, and the risk applies to the agent as much as to you. Each skill also forces the agent to explain itself in terms you can check, which is how you supervise an agent that may know the code better than you do.

The chapter covers 7 skills:

  • /how explains how the code works now;
  • /why recovers the reasons it was built that way;
  • /recall rebuilds your own recent working context;
  • /in-your-own-words plays your goal back to you before work starts;
  • /figure-it-out designs a custom playbook when none of the built-in ones fits;
  • /interrogate asks adversaries to break a change and keeps only proven findings;
  • /blast-radius looks for breakage outside the diff and proves the fact that makes a change safe.

/teach, which combines /how and /why into one explanation, belongs to Learning and Communication.

/why: answer from the record, not from the code

Source

  • What it does: it explains the rationale behind a piece of code by reading the commits and pull request discussions that introduced it, followed by each later change. When that trail is thin, it consults other sources.
  • When to use it: questions such as “why does X work this way” or “why did we pick Y”, design rationale, regressions, postmortems, and the origin of a data-backed threshold. For runtime behavior, the description points you to /how instead.
  • How it proceeds: it cites what the authors actually wrote, labels its own inferences as inferences, and states which parts of the question the record does not answer. The guide notes that a missing explanation is itself a finding.
  • Caveats: the skill is deliberately constrained to the historical record, so it should not reconstruct a motive from the shape of the code. It runs only when invoked.

A typical prompt from the guide is /why was the retry limit set to five? does the reason still hold?. When you suspect that history explains a confusing design, the guide suggests asking for /why first and /how second.

/how: a working mental model of a subsystem

Source

  • What it does: it answers “how does X work?” with an architectural explanation pitched at a senior engineer who is new to the area and needs enough of a model to start working there with confidence.
  • When to use it: code walkthroughs before a change, explanations of runtime flow, onboarding, and questions about placement, ownership, and layering (“where should this live”, “which package owns this”, “is this the right layer”).
  • How it proceeds: if the scope is ambiguous, the agent states how it interprets the question and starts exploring; you can redirect it. It then spawns one subagent (subagent_type: generalPurpose, readonly: true) that explores the codebase and writes the explanation in a single pass. The main agent presents that output with only light edits for clarity or conversational context.
  • Caveats: the skill tells the main agent not to rewrite the subagent’s explanation substantially. Motivation and history are outside its scope; that is the job of /why.

The guide recommends asking the question you actually have, for example /how do we dedupe notifications? is there an n+1 when we look up subscribers?.

/recall: rebuild your recent working context

Source

  • What it does: before you start or resume work, it reconstructs your recent context on a topic and returns a compact brief on where things stand and what to do next. It draws on 2 records: your own chat history (what you did and decided) and the shared record, meaning source control, the issue tracker, chat and issue channels, long-form documents, and error tracking.

  • When to use it: prompts such as “recall my work on X”, “catch me up”, “what have I been working on”, or “where did I leave off”. It is most valuable for a feature with a long tail of bugs, because most of that story lives outside your own chats.

  • How it proceeds:

    1. Classify the request. Resuming one specific earlier chat is the job of the session-pickup playbook, and turning habits into a lasting skill is /automate-me. If you have already supplied a full state capsule (paths, branch, the change), the skill uses it and skips the mining.
    2. Lock the scope. It fixes the time window (“recent” defaults to the last 7 days), the topic, and the workspace, then states the scope back to you. It never narrows “all” to “recent” without saying so, and it does not read another project’s transcripts unless asked.
    3. Mine the chat history in parallel. Subagents on a fast, inexpensive model each take a slice of the transcripts, which Cursor stores under ~/.cursor/projects/<slug>/agent-transcripts/. Each one orders candidates by modification time, searches for the topic before reading, and reads only the relevant regions. All of them return the same fields per chat: topic, goal, decisions, open threads, struggles and corrections, and artifacts, each citing the chat UUID. The raw transcripts stay inside the subagents.
    4. Sweep the shared record. Whenever the topic names a feature, file, subsystem, area, or bug, one investigator subagent per source asks what the current state is, what has been tried and failed to hold, and what users are still reporting. This step is the default, and an empty result counts as a finding. Only pure activity recall (“what did I do this week”) skips it.
    5. Check live state. It verifies the pull requests, branches, and tickets that surfaced against reality with git and gh.
    6. Write the brief.
  • Output: the brief follows a fixed contract:

    PartContent
    CapsuleAt most 5 bullets on what the work is and where it stands
    ThreadsOne line each, with exactly one status tag such as [merged #N], [open PR #N], [in flight <branch>], [verified, uncommitted], [reverted #N], or [planned, not started]
    ProblemsAt most 5 recurring problems, including symptoms users keep reporting and fixes that shipped and were reverted
    Next moveThe single most useful next action, stated concretely
  • Caveats: adjacent features stay out of the brief unless they block this one. The brief is written through /unslop, cites chat findings by UUID and shared-record findings by their source, and has private context removed before any public output.

The guide suggests loading context before handing over new input, for example /recall my work on the virtualized list from yesterday, then read this bug report.

/figure-it-out: design a playbook when none fits

Source

  • What it does: for a task that matches no built-in playbook, such as a large migration or an ambitious multi-part change, it designs one. The first deliverable is the workflow itself: a sequence of phases whose rigor matches the task, run as a hypothesis loop, with a decision trail that a human can audit after stepping away.

  • When to use it: work for which no narrower playbook exists, especially when you want to leave the agent working and later confirm that it did the job correctly.

  • How it proceeds: it opens a todo list whose first item is to read the Principles section of /poteto-mode, then works through 5 phases.

    PhaseWhat happens
    A. FrameDefine “done” as a falsifiable predicate, quantify the scope, and choose a rigor level, biased towards high. One-way decisions and wide blast radius earn more rigor; reversible, low-stakes steps earn less. A multi-hour run gets one checkpoint where the framing and trade-offs are shown before work starts.
    B. Design the workflowSplit the work into atomic units that can land independently, riskiest unknown first. Build the verification setup and capture a baseline before any change, so results read as old value against new value. Use /architect (which runs /arena) only for one-way design decisions. Parallelize only across real seams, with a separate worktree or branch per worker. The written phase list is what the human reviews.
    C. Run the loopTreat each unit as an experiment: state a hypothesis, make the smallest change, measure it on the real artifact, keep it if it helped, and revert it if it did not. Verify each unit before starting the next. Every verdict is VERIFIED, NOT VERIFIED, or INCONCLUSIVE, and INCONCLUSIVE is not a pass.
    D. Keep the audit trailLog decisions with /show-me-your-work, adding a row as each step lands. For ambitious work, commit the trail so the reviewer can read it in the pull request.
    E. Verify and hand backCheck the whole result against the Phase A predicate on the real product, not only the verification setup. Encode any recurring correction as a gate, lint rule, check, or script.
  • Caveats: when something passes too easily, the skill suspects the observation method before the system. Delegated work is paired with a judge; if a worker games a gate, the contract is reset and tightened, and if the gate itself is wrong, it is fixed in a separate change. The reply names the designed playbook, the rigor level and the reason for it, the path to the decision trail, what is verified, and what remains open.

/interrogate: adversarial review that keeps only proven findings

Source

  • What it does: it sends adversaries, each running on a configured model, to break a change or a design. A finding survives only when a run proves it. The skill reports findings and applies no fixes.
  • When to use it: requests such as “interrogate”, “adversarial review”, “multi-model review”, “challenge this”, “stress test this code”, “find blind spots”, or “tear this apart”.
  • How it proceeds:
    1. Frame. If you name a scope, that is the scope; if not, it covers the branch diff, running from the merge base with the base branch up to the working tree. Using /in-your-own-words, the agent restates the intent from your message, the commits, and the pull request description, and it asks you when the intent remains unclear.
    2. Fan out. It reuses the runner selection, the per-candidate worktrees, and the parallel launch from /arena, but reads the interrogate reviewers line of the model configuration instead of arena runners. Uncommitted changes are copied into each worktree. Each adversary is told to prove every finding with a run against the real code (a failing test, a repro script, or command output showing wrong behavior), to probe a prototype or the current tree when the target is a design, and to omit anything it did not run.
    3. Verify. The agent reruns each finding’s command. It keeps a finding when the output shows the failure and that failure breaks the intent, drops the rest, and merges findings that share a root cause.
  • Output: the restated intent; every verified finding with its command, its output, how it breaks the intent, and which adversaries found it; and, per adversary, the number of dropped findings and why. “No verified findings” is a valid result.
  • Caveats: style, naming, structure, and risks that would matter only after some future change are excluded from the start, because no run can prove them. The skill skips the cross-judge, base selection, and grafting phases of /arena: adversaries find different failures, so the verdict keeps every verified finding instead of choosing one adversary’s list. The guide advises reading the Dropped list as well, since you can override the verdict, and warns that an abstract plan with no code behind it gives the adversaries little to break.

/in-your-own-words: restate the goal before starting

Source

  • What it does: the agent restates, in its own words, what it believes your goals are and which problem you are trying to solve. The entire body of the skill is that one instruction.
  • When to use it: at the start of a large or ambiguous request, so that a misunderstanding surfaces before any code is written. /interrogate uses it to state the intent of a change.
  • How it proceeds: the agent reads your request and plays back the goal and the problem. If the restatement is wrong, you have found the misunderstanding cheaply.
  • Caveats: the output is the restatement and nothing more. The skill runs only when you type /in-your-own-words.

/blast-radius: find what breaks elsewhere, and prove the safety fact

Source

  • What it does: before a change ships, it looks for what the change could break outside the diff. The skill calls itself a companion to /how (what the code does) and /why (why it has that shape); blast radius answers what it breaks somewhere else. Listing callers is explicitly not the job, since grep finds them in seconds. The job is the breakage grep cannot show.

  • When to use it: “Blast radius of X”, “what could this break”, or a small diff that you do not yet trust.

  • How it proceeds:

    1. Read the change: the diff, the symbols it adds, changes, and deletes, and the behavior that differs even where the diff does not spell it out. Pull the pull request and its commits.
    2. Find the one fact the change is safe because of, for example that a call only drops cache entries that are already dead. If that fact holds, most risky cases are cleared at once, so this step deserves most of the time.
    3. Look where grep stops: the source of the libraries being called, including their pinned versions and local patches; timing such as microtasks, unmount and teardown, or Solid compared with React; and data paths a symbol search misses, such as API responses, database columns, wire formats, another language reading the same bytes, feature flags, or code 3 hops downstream.
    4. Be honest about each risk: give it a realistic probability and cost, cite a real file:line, keep confirmed risks separate from checked and cleared ones, and never invent a caller or an API. A search that finds nothing is still an answer.
    5. Prove the one fact with a script or test that runs the real code, and paste the result.
    6. For a large or wide change, run it as an arena, because different models catch different real bugs.
  • How sure the agent is: the skill grades each fact on a 5-step scale and asks the agent to say where it stopped:

    StepEvidence
    1The agent said so (worthless on its own)
    2It pointed at the line, either a real file:line or the library’s source
    3It walked the failure step by step and showed it cannot happen
    4It ran a script or test against the real code that fails loudly if the claim is wrong
    5It reproduced the behavior in the running app
  • Output: what the change does, including the non-obvious part; the safety fact, the step it reached, and its proof, or the word “unproven”; the risks with file:line, likelihood, severity, and how to check; what was cleared and why; and the cheapest test or repro to run before merging.

  • Caveats: the skill’s central warning is that a convincing writeup is worthless as evidence, because it reads the same whether or not it is true. The result is written through /unslop, and private details are removed before anything goes public.

Two /poteto-mode playbooks complement these skills. The Investigation playbook handles a read-only question; a prompt that ends with “don’t change any code yet” routes there, and it returns a cited explanation or, for a choice between options, a recommendation with a trade-offs table. The Session pickup playbook takes over a branch that another agent left mid-flight, treats the prior trail as authoritative, and verifies inherited claims against the original goal. Both are covered in the playbook chapters.

Design

The skills in this chapter settle the shape of a change before code commits you to one. A single attempt at a hard design tends to lock in the first shape the model thought of, and discovering the mistake after implementation is far more expensive than resolving it beforehand.

The chapter covers 3 skills:

  • /architect sketches types, signatures, and module boundaries;
  • /statechart model-checks a system that moves between states and draws it for the person who owns the behavior;
  • /arena runs several independent attempts at the same task and merges the best parts.

Two related skills live elsewhere. /interrogate, which asks adversaries to break a finished design or change, is in Understanding and Investigation. /swarm, which fans workers out across independent slices or races and aggregates their reports, is in Operations and Automation; unlike /arena, it gives each worker a different scope and does not pick a base or graft.

/architect: sketch the shape before you code

Source

  • What it does: before any code is written, it traces every system the change touches and then sketches 2 different shapes for the change, each expressed as types, function signatures, and module boundaries. According to its description, it then stays in the loop while the implementation fills in the chosen shape.
  • When to use it: non-trivial work that crosses function boundaries, where starting with code would fix the wrong shape in place. Typical triggers are /architect, “architect this”, and “design this”.
  • How it proceeds: it compares the 2 sketches against 3 criteria and keeps the one that does best.
    • Each piece of state has exactly one owner.
    • Each task has exactly one way to be done.
    • Callers need to know as little as possible.
  • Caveats: when one workaround keeps coming back during implementation, the skill revisits the design rather than patching around it. A large or disputed design goes to /arena instead of being sketched by a single agent. To review the design yourself before any code is written, state that in the prompt.

The guide gives this example: /architect design the import pipeline before writing any code. i care most about how callers use it. It adds that /poteto-mode already calls /architect on its own for work that crosses boundaries; a direct call is mostly useful when you want a level of scrutiny above or below the default.

/statechart: check a state machine and show it in the reader’s words

Source

  • What it does: given a TLA+ model of something that passes through states (a product flow, a protocol, or a service), it runs the TLC model checker and renders the outcome as a Mermaid statechart. For every state that violates a rule, the report shows the shortest path leading there. The skill refers to whoever reads the chart as the reader, and it is the reader who judges whether the behavior is correct.
  • When to use it: when someone who owns a behavior needs to see it instead of reading a specification, or when you want to present a bug as a path through states.
  • How it proceeds:
    1. Write a TLA+ spec and its config in a scratch folder outside the repository. Every rule the reader agrees to becomes an INVARIANT, and if the model has no variable for a rule, you add one. A rule is never weakened to make it hold. Next should be written as a disjunction of named actions, otherwise TLC labels every step Next. Because a state with no outgoing step breaks NoDeadlock, even a correct end state needs an explicit action that is true only there and changes nothing.
    2. Run the bundled command: <skill dir>/scripts/statechart SPEC.tla [--config FILE] [--view FILE] [--out DIR]. The script is TypeScript, so it needs a runtime that can execute TypeScript, and the first run installs TLC and Java with mise, which requires network access.
    3. Write a view module, passed with --view, that carries the judgment calls. Its state(vars) function maps model values to the reader’s labels; returning a string gives a flat chart, an array gives nested parent states, and an object gives one parallel region per key. Its optional step(action, from, to) labels each arrow as the user experiences it, such as “you press play”, with conditions in brackets. Optional group, colors, and title exports set phases, colors, and a heading.
    4. Show chart.mmd to the user as a mermaid code block, rendering it with the Pele package when an image is needed.
    5. Hand off the chart and its Mermaid text to the person who must decide, with one line per bug: the rule, the reader’s sentence for that rule, and the numbered path from the report. Say what the model leaves out, and give the command that regenerates the files.
  • Keeping the chart readable: labels use what the reader can see or cares about (“Paying”, “Lease held, write pending”) and never variable or action names. The target is about 20 arrows or fewer, reached first by coarser labels and then, if necessary, by returning null from step() for steps the reader does not need. States on a bug path must stay, and 2 states that break different rules must never be merged, because the reader would no longer see which rule breaks where. Hidden steps must keep every chart state reachable, and the hand-off must say which steps are hidden.
  • Reading the report: a state that breaks a rule is marked breaks, and one where only some underlying model states break it is marked mayBreak. Because TLC continues past a violating state, the chart also shows what happens after a bug. The command checks the config as written; each time a rule breaks, it removes that rule and runs TLC again, and after the first break each run stops at 100,000 distinct states. Rules left unchecked by that bound or by an error appear under “Rules not checked”, and they may hold or break.
  • Caveats: a model without a limit on its states can run without end, so keep constants small or add a CONSTRAINT. The chart has a budget of 500 states; above it, only the paths to broken rules are drawn, and if nothing breaks, no chart.mmd is written at all. When the model describes real code, each bug path must be replayed against that code as a test or a live repro, one step per action. If the bug does not occur, assume the model is wrong until you show otherwise.

/arena: several attempts, one merged result

Source

  • What it does: it spawns N candidates that attempt the same task in parallel, picks one result as the base, and grafts the strongest parts of the other candidates into it. This guards against a single attempt locking in the wrong shape for a non-trivial artifact.

  • When to use it: designs, code, documents, and standalone decisions such as names, formats, or algorithms, where the first shape is costly to change later. Triggers include /arena, “arena this”, and “throw it in the arena”. /architect also calls it for large or contested designs.

  • How it proceeds: it first opens a todo list with one entry per phase.

    PhaseWhat happens
    A. FrameAll candidates get an identical prompt, which therefore serves as the contract. Name the artifact, then work out a rubric of 3 to 6 concrete criteria for this task that can be graded; the rubric is shown to the picker only. Take the runners from the arena runners line in the model configuration (by default claude-fable-5-2-high, claude-opus-5-5-high-fast, and gemini-4-neon-high), and assign every candidate a separate output location: a git worktree if possible, and /tmp/arena-<slug>/candidate-<n>/ if not.
    B. Fan outLaunch all candidates in one message, in the background. Each produces the artifact plus a short rationale naming the alternatives it considered and rejected. If one produces nothing, continue with the rest and record the dropout.
    C. Cross-judgeSpawn one read-only judge from the arena cross-judge pool line, never from the parent model’s vendor (Fable counts as Claude for this check). The judge scores each candidate, identified only by its path label, on every rubric criterion and recommends a base.
    D. Pick a baseRead every candidate end to end and score it criterion by criterion, not on overall impression. Agreement with the judge confirms the pick; disagreement means bias on one side or an ambiguous rubric, so both rationales are reread. The base is the one a future maintainer can extend most easily without breaking invariants, and a tie goes to the cleaner boundary or the smaller API.
    E. GraftWalk each losing candidate once more for the 1 or 2 ideas worth porting, and fold each one in by hand so the result stays coherent under one mental model.
    F. VerifyVerify the merged artifact like any other output. A problem found here means either the framing was wrong (reframe and rerun) or a candidate had caught it and the graft was missed (return to Phase E).
  • Output: one merged artifact with a short synthesis note that names the base and the reason, the judge’s verdict or the fact that the judge was skipped, the source of each graft, what was rejected and why, any convergence or dropouts, and the verification result.

  • Caveats: if the candidates converge on one shape, that is strong agreement, and the consensus ships without grafts. If they diverge wildly, Phase A was under-specified, and the right response is to reframe and rerun instead of averaging the divergence. Runner fallbacks are explicit: an unavailable model is replaced by the nearest valid slug of the same family or dropped, at least 2 runners must remain, and the agent says what it changed. You can ask for more candidates when a decision matters, and the skill allows repeating one model when the work is bound by generation volume rather than judgment.

The runner panel comes from your /setup-pstack configuration and can be adjusted per task, for example /arena this, 5 candidates. the cache key format is expensive to change later.

How much design a task deserves

The guide is clear that most changes need none of this. It offers a rough ladder, which /poteto-mode already applies on its own:

SituationTool
A small, finished change you are unsure about/interrogate alone
A change that crosses function boundaries or moves ownership/architect, which brings in /arena when the design is large or contested
A standalone decision that independent attempts would improve (naming, formats, an algorithm)/arena directly
A coverage matrix, a set of parallel checks, or a race with declared arms/swarm
An open question that running something could answer (a layout, a timing, an approach)A prototype, not a debate
A contested design that is expensive to reverse/architect, then /interrogate before shipping
Work that spans several pull requestsA plan, written after the design settles

pstack has no dedicated planning skill. The Prototype and Multi-phase plan playbooks cover the last rows of this table: prototypes answer open questions by running code, and the plan is written only once the design has settled. Both are described in the playbook chapters.

Building and Code Quality

These skills apply while you write and clean up a change. /tdd turns a bug into a failing test before the fix, /correct changes a repository so that repeated agent mistakes can no longer happen, /sharpen rewrites a request so that the work goes deeper, /unslop removes AI habits from prose, /no-comments hands the comments in a diff to a separate reviewer, and /typescript-best-practices makes illegal states impossible to write in TypeScript.

All 6 skills set disable-model-invocation: true in their frontmatter. The agent never starts them on its own judgment, so each one runs only when you type its name.

The build guide (05-build-and-clean.md) frames these skills with a single habit: state what you observed, and let the skill or playbook demand the evidence.

A playbook is a step-by-step workflow for one kind of task. Bug, feature, refactoring, and performance prompts go through /poteto-mode, the entry skill that picks a playbook for a request. The playbook chapters cover those playbooks. This chapter covers the skills you call by name.

/tdd: make the bug fail as a test before you fix it

Source: skills/tdd/SKILL.md

  • What it does: For a bug with a clear and cheap test path, it writes a focused regression test that fails before the fix and passes after it. A regression test here means a test that would have caught this specific bug.
  • When to use it: Only if you request TDD, a failing test, or a regression test, or if the bug offers an obvious local test target that is cheap to write. According to the skill, the agent should not use it when the test path is unclear or costly, or when it would rely heavily on integration. The guide demonstrates that /tdd implement works as a full prompt once the context is sufficient.
  • How it runs:
    1. Understand the bug: the intended behavior, the current behavior, the affected path, and the smallest observable reproduction.
    2. Pick the narrowest executable check that already exists for that code path (unit, component, integration, or regression test). If no practical test path is obvious, the skill does not build one from scratch just to follow the workflow.
    3. Write the smallest test that would have caught the bug. It encodes the intended behavior and does not mirror the current implementation.
    4. Run the test before making the fix and check that its failure has the intended cause. If it passes, or fails for some other reason, repair the test or the reproduction before going further.
    5. Make the smallest production change that satisfies the intended behavior and keeps nearby contracts intact.
    6. Rerun the regression test and confirm it passes.
  • Points to watch:
    • When a failing test is impractical (it would need broad test setup, brittle mocks, slow end-to-end infrastructure, production-only state, or large fixture churn), the skill switches to the closest executable check: a targeted script, a manual reproduction command, browser automation, a snapshot comparison, a log assertion, or a focused integration check.
    • The skill would rather add no test than a bad one. A test is bad if it mainly exercises mocks, locks in implementation details, relies on timing or on unrelated global state, demands costly infrastructure for a small fix, or would be removed as soon as it had proven the fix.
    • Tests must not be rewritten to match a wrong implementation, and existing assertions must not be weakened unless the expected behavior has truly changed. For a flaky bug, the test should be made deterministic where possible. If the bug points to a wider class of failures, the focused regression lands first and sibling coverage comes later.
    • The final reply reports the evidence along with the outcome: the test or check that failed before the fix and how it failed, the run that passed afterwards, and, if no failing-before evidence was possible, why and what check replaced it.

/correct: turn repeated mistakes into ones that cannot happen

Source: skills/correct/SKILL.md

  • What it does: It finds the classes of mistakes that agents keep making in a repository and changes the repository so the next agent cannot make them. The skill is meant to run again each time the operator (the person supervising the agents) corrects an agent.
  • When to use it: When you type /correct, typically in a repository where the same correction keeps coming back.
  • The working assumption: The skill models every contributor as an agent that sees nothing beyond the files it has opened, imitates the closest example, and chooses the shortest route to code that compiles. It aims for a repository in which any change that seems correct from the viewpoint of 1 file is also correct for the repository as a whole.
  • How it runs:
    1. Go through recent commits, reverts, review comments, agent instruction files, and code comments describing workarounds. Sort the mistakes into classes, and treat a class as real once it has occurred 2 times.

    2. Fix each class at the highest level that works, in this fixed order:

      LevelWhat it means
      ArchitectureGive each piece of state 1 owner and each task 1 supported way. Hide internals so that the wrong import fails. Replace hand-synced lists with a single source of truth. Delete old ways and dead code that an agent might copy.
      TypesMake the bad state impossible to write. If bad code still compiles, add a lint or CI check whose error message names the file, type, or function to use instead. For a pattern that is already common, fail only when a change adds more of it.
      TestsTest the behavior. Fix or delete any test that still passes when its behavior breaks, or that fails when only the internals change.
      Docs and agent rulesLast, and only for judgment calls. Nothing fails when an agent skips them.
    3. Fix the most frequent classes first, with 1 commit per class. Prove that each new check fails on a real past mistake, and run the same command locally and in CI. An exception goes on the offending line with a reason, an expiry date, and a human’s approval.

    4. Maintain a table in the agent instruction file that matches every rule to the mechanism enforcing it. Whenever the operator corrects you, fix the mistake and record the rule. If the rule was already there but had no enforcement, count this as a repeat and address it at the highest possible level in the same change. Once a mistake has become impossible, delete its rule.

  • Points to watch: The reply lists each class with its evidence, the level chosen, and why a higher level did not work.

/sharpen: make a task deeper before you rewrite the prompt

Source: skills/sharpen/SKILL.md

  • What it does: It rewrites a request so that it asks for a “deeper version of this task, not a bigger one”. It applies to any kind of task, including tasks unrelated to code.

  • When to use it: When you type /sharpen, usually before handing off a request that you suspect is shallow.

  • How it runs: Before rewriting, the agent answers 4 questions:

    1. What would a top professional in this field do here that the request does not ask for?
    2. What is the rawest material they would start from, instead of material that someone has already digested?
    3. Which specific methods and tools would they use?
    4. What, other than the agent or the user, would show that the result is right?

    The agent then rewrites the prompt to ask for exactly that. The rewritten prompt tells the agent to prototype any choice that an experiment can settle and to recommend an option based on what it observed. Product or preference choices that no experiment can settle stay with the user.

  • Points to watch: The 4th question makes the agent name an independent verifier before any work starts.

/unslop: remove AI habits from any writing

Source: skills/unslop/SKILL.md

  • What it does: It scans text for patterns typical of AI writing and rewrites them, keeping the meaning and the intended tone. “Slop” is the general name for this kind of filler.

  • When to use it: On any prose: READMEs, PR descriptions, commit bodies, logs. /poteto-mode applies it to PR descriptions and commit bodies. The guide shows that it accepts a target and extra rules, as in /unslop the readme changes, no emdashes, and that terse prompts such as unslop that, tighten it also work.

  • The rules, grouped: Each rule has a stable number that other skills cite. When a rule is removed, its number stays empty, which is why the list starts at 3 and skips 4, 6, and 21.

    GroupRules
    Empty phrasingNo trailing “-ing” phrases that add no fact (3). No vague attributions such as “experts believe”; name the source or delete the claim (5). Cut filler phrases and replace long connectives with short ones (23). End with a specific plan or fact, never a generic conclusion (25).
    Word choiceAvoid typical AI vocabulary such as “crucial”, “enhance”, “foster”, “pivotal”, “showcase”, “testament”, “underscore”, and “vibrant” (7). Say “is” or “has” instead of “serves as”, “stands as”, “boasts”, or “features” (8). Use the plain word, such as “use” (31). No abstract metaphor nouns such as “substrate”, “wedge”, “paradigm”, or “flywheel” (26).
    Sentence shapeNo “not just X, but Y” (9). Do not force ideas into groups of 3 (10). Use 1 name per thing and repeat it (11). No “from X to Y” unless X and Y sit on a real scale (12). 1 idea per sentence (28). Active voice with a named actor (29). Whole sentences with articles and verbs; spell out arrows and abbreviations (33).
    Punctuation and formatNo em dashes, en dashes, or hyphens used as dashes, and no parentheses in their place (13). A colon only before a list or an example (14). Do not bold every proper noun (15). No bold label that only restates its line (16). Sentence case headings (17), no decorative emojis (18), straight quotes (19).
    ToneNo chatbot phrases such as “I hope this helps!” (20). No praise or agreement at the start of a reply (22). At most 1 hedge, “may” (24).
    ConcretenessSay what something does, naming the mechanism or the number, and cut any sentence that could appear unchanged in another project’s docs (27). Cut adverbs or use a stronger verb (30). No metaphor, aphorism, or personified code where a literal phrase exists (32).
  • Points to watch: Never renumber the rules: other skills refer to them by number. The guide separates 3 cleanup jobs. /deslop, which comes from the separate cursor-team-kit plugin and is not part of pstack, cleans slop out of code; /unslop cleans it out of prose; /no-comments hands comments to a reviewer who did not write them. Without /deslop, the guide suggests asking in plain words for the same result: remove narrating comments, unsupported guards, dead compatibility paths, and unrelated edits.

/no-comments: let a separate reviewer judge the comments

Source: skills/no-comments/SKILL.md, with the reviewer defined in agents/comment-sicko.md

  • What it does: It spawns Comment Sicko, a subagent that hates comments and edits nothing except comments, then acts on the findings it accepts. For comments that claim a constraint, it offers to encode the constraint in code instead.
  • When to use it: When you type /no-comments, typically on a diff before review. The guide’s reasoning is that an author defends its own comments, so another agent should judge them. The scope is the files or diff you pass; otherwise it is the current diff against the base branch (default main), including the working tree.
  • What Comment Sicko keeps: Only a few kinds of comment survive. These are legal or license headers; explanations of non-obvious behavior imposed by an external dependency, platform, vendor, or protocol that cannot be changed; // prettier-ignore; lint suppressions for a rule that is faulty, pedantic, or purely stylistic; doc comments defining the contract of a public API; and links to issues or RFCs describing a constraint the code has no way to express. All other comments are removed. If a comment explains surprising behavior in the project’s own code, Sicko removes it and tags the exact symbol with MUST KILL, which requests a rename, an extraction, a type, or a redesign so that the behavior becomes obvious without any prose. The same MUST KILL flag goes on a suppression such as @ts-ignore when its rule guards correctness or safety. Sicko edits comments and nothing else; it never writes application code.
  • How it runs:
    1. Spawn Task with subagent_type: "comment-sicko" and pass the scope. The reasoning level follows the Subagents section of /poteto-mode. The parent does not restate Sicko’s rules.
    2. Inspect the report and the diff.
      • Reject edits to application code, changes outside the scope, deletions that an exception protected, MUST KILL flags with a misstated reason, and flags that treat intentional code as guilty.
      • A keep survives only with proof that it concerns something the project cannot change. The parent also checks for scoped lint and TypeScript suppressions that Sicko missed.
      • Before accepting a thin IMPORTANT or do not remove verdict, the parent traces the symbol or runs /why. An ambiguous kill is not restored; a refuted or still ambiguous keep is deleted.
      • A rejected report is reverted and rerun once with the failure named. If the second report is also rejected, the parent reports it as open and /no-comments fails.
    3. Fix trivial accepted flags directly: delete a dead path, drop a parameter, or call the real API. If any fix needs a new shape, run /architect once for the accepted set and stop at its sketch.
    4. Implement the smallest root-cause fix inside the scope and remove every named workaround. If the root cause lies outside the scope, land the smallest in-scope fix and report the rest as open. The skill forbids adding guards that only hide symptoms.
    5. For constraint comments (do not remove, do not change wording, talk to X before changing), leave keeps about things the project cannot change. For the others, offer the cheapest in-scope type, runtime check, test, or CI lint and wait for approval; unattended runs and evals need the caller’s approval in advance. If approved, encode the constraint and then delete the comment. If not, delete it anyway, report the constraint as open, and sketch the out-of-scope work.
    6. Report the deletion count, restored comments, reruns, the architect sketch, fixes, encoding offers and encodings, unenforced constraints, and other open work.
  • Points to watch: The skill tells the parent to defer to Sicko’s fresh perspective, while step 2 still gives the parent a precise list of reasons to reject a report. Either way the comment comes out: a claimed constraint ends up either encoded or reported as open.

/typescript-best-practices: make illegal states impossible to write

Source: skills/typescript-best-practices/SKILL.md, with examples in references/patterns.md

  • What it does: It turns the type-system principles into concrete TypeScript rules. It first applies principle-type-system-discipline.
  • When to use it: Whenever a task reads or edits .ts or .tsx files. The frontmatter declares those files in paths, but because model invocation is disabled the skill does not load on its own; the guide says to type /typescript-best-practices yourself.
  • The rules, grouped:
    • Modeling: Represent variants as discriminated unions with a kind literal, never as a bag of optional fields. Brand primitives with & { readonly __brand: "X" } so that values cannot be mixed up, and obtain a brand only from a type guard that verifies it, never from as. Build shapes so that illegal values cannot be constructed: [T, ...T[]] for a non-empty list, [T, T][] for an even length, a start plus a duration for a range. Keep the simplest total type (plain T[]) while every operation on it stays total, and strengthen it only where the loose type forces !, a cast, or a “should never happen” throw.
    • Validation at the boundary: External data is unknown, not any. Before writing a property-by-property guard, infer the type from the repository’s runtime schema library (for example z.infer). Cast with as only after validation. Parse data into a named domain type where it enters, so that Record<string, unknown> goes no further, and trust the types inside (see principle-boundary-discipline). Derive types with Pick, Omit, Parameters, ReturnType, Awaited, or typeof before declaring a new interface.
    • Narrowing: Prefer, in order: a discriminant switch, the in operator, typeof or instanceof, a user-defined type guard, and only then as. A guard must verify what it claims; a lying guard is worse than as because its name says the value is safe. Name guards isX or hasX. Put const _exhaustive: never = x; in default branches so that adding a variant causes a compile error. Use satisfies instead of as to validate a value without widening its literal types.
    • Other practices: Pass an object rather than positional arguments, except on hot paths such as per-frame rendering, tokenizers, and parsers. Do not mock what you can run: use the framework’s real test primitives with leak and disposal checks, and verify UI in a running build. Ship no console.log; use structured logger diagnostics with enough context to debug from an id.
  • Points to watch: The goal is a codebase where illegal states cannot be written. The “simplest total type” rule limits stronger types to the places that actually need them.

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.

Operations and Automation

These skills support the daily running of agents. /automate-me turns your own working style into a personal skill, /swarm sends work to parallel workers and merges their results, /ketchup and /ketchup-video catch you up on what happened while you were away, and /make-bot-ui builds a page whose buttons wake a bot over a webhook.

All 5 skills set disable-model-invocation: true in their frontmatter, so each one runs only when you type its name or trigger phrase.

/automate-me: turn the way you work into a personal skill

Source: skills/automate-me/SKILL.md

  • What it does: It captures your working conventions in a single personal “mode skill”, a skill named <handle>-mode (for example jay-mode) that tells later agents how you like work done. It coordinates 3 other pieces and replaces none of them: an inline pass that mines your chat history, Cursor’s built-in create-skill skill (which is not part of pstack) for authoring, and /unslop for the prose.
  • When to use it: When you say “automate me”, ask to create, update, or refresh your -mode skill, or want your preferences and working style turned into a skill.
  • How it runs:
    1. Look for an existing mode skill, searching .cursor/skills/**/*-mode/SKILL.md and ~/.cursor/skills/*-mode/SKILL.md for your handle. If one exists, confirm with the AskQuestion tool whether to update it (the default) or start fresh (rare, and only after asking why). In update mode, mining covers only the history since the file was last edited, the questions ask what has changed or is missing, and the existing file is edited in place.
    2. Mine your history. The skill reads only the current workspace’s agent-transcripts/ directory and never globs across other projects, which would expose private chats from unrelated work. Several subagents run in parallel over slices of recent history (for example the last 2 to 4 weeks, in 3 slices) and look for response preferences, delegation habits, verification posture, code and prose discipline, process conventions, and meta preferences such as fixing skills during a task. A pattern seen in at least 2 slices is a strong signal; a lone one is usually dropped.
    3. Ask you directly with AskQuestion: 1 or 2 multiple-choice questions with 4 to 6 options each, followed by 1 free-form question to catch anything the options missed.
    4. Group the signals into sections such as response style, autonomy, subagents, review and verification, process, and skills, using only the ones that apply. The skill points to /poteto-mode, the mode skill at the center of pstack, as an example of the right granularity but warns against copying its content.
    5. Draft the skill with create-skill. A new mode skill goes in .cursor/skills/<handle>-mode/SKILL.md (or a personal category directory if the repository already has one). Its description triggers on your name, /<handle>-mode, and “work in their style”, and it sets disable-model-invocation: true unless you want it on every turn.
    6. Apply /unslop and the authoring guidelines, show you the draft, and expect several rounds of revision.
    7. Commit in a worktree off main and open a PR; never push to main directly.
  • Points to watch:
    • Do not turn a preference stated once into a rule. Refer to other skills by path instead of pasting their content. Add a section only where you have a specific, non-default rule, and skip areas such as process entirely if you have none.
    • Evaluation is a check with you (“does it read like me? did it miss anything?”); the skill considers a benchmark loop unhelpful for such subjective output.
    • It is the wrong tool for a task-specific skill or for a single narrow workflow such as how you write commit messages. Those are ordinary skills, which create-skill can write without any mining.

/swarm: fan out parallel workers and return a single report

Source: skills/swarm/SKILL.md

  • What it does: It runs N workers in parallel, waits for all of them, and returns a single consolidated report. The work can be partitioned into slices, raced (N workers on identical briefs), or a mix of both.
  • When to use it: For /swarm, “swarm this”, or any job that needs parallel coverage, races, gauntlets, or exploration.
  • How it runs: The agent first opens a todo list with 1 entry per phase, then works through 4 phases.
    1. Frame.
      • State the “done predicate” (the condition under which the swarm is finished) and the artifact or report it must return.
      • Choose the shape, and for a race or a mix declare the selection rule before spawning: first pass, rank all, or best-of.
      • Take the worker model from the swarm workers line in ~/.cursor/rules/pstack-models.mdc, falling back to claude-opus-5-5-high-fast if the file or line is missing; auto or inherit-parent means the workers run on the parent’s model.
      • Give each worker that writes its own writable output. Workers that verify or measure commits get the exact SHAs, and a measurement brief also names the method (sample count, what 1 sample is, and the order).
    2. Fan out.
      • Spawn all N workers in 1 message as generalPurpose subagents with environment: "cloud" and run_in_background: true. Use environment: "local" only when a worker needs something on your computer, and pass cloud_base_branch when a worker must start from a non-default pushed branch.
      • Every brief stands alone, with the goal, scope, slice or race arm, verification method, and what to report.
      • Workers answer PASS, ISSUES, or BLOCKED with evidence, and a worker that can prove defects lists all of them, not only the first. If a worker drops out, the swarm continues with N-1 and notes it.
    3. Aggregate. Read the final results. A result that does not record the SHAs and method its brief named is dropped and that worker is respawned once; after a 2nd miss the slot is recorded as a gap, and a gap never counts as a pass. Coverage needs a result for every slice, and a race applies the rule declared in Frame. Raw worker output is never pasted.
    4. Report. Return a single in-chat report with a result table, a one-line summary per issue, any gaps or dropouts, and the race rule when one was used.
  • Points to watch: Each worker’s reasoning level follows the Subagents section of /poteto-mode, the entry skill of pstack. If the Task tool rejects a model slug, the agent uses the default and says so.

/ketchup: catch up on what changed, in plain words

Source: skills/ketchup/SKILL.md

  • What it does: It explains what changed in this chat since the last message you wrote, in plain words and small visuals, and lists every decision waiting on you with enough detail to make it from the reply alone. Notifications and subagent results do not count as your messages; the skill assumes you remember your last message and nothing after it.
  • When to use it: When you type /ketchup after being away while agents and subagents kept working.
  • Voice: It borrows the voice of /bro (plain words, short sentences, no jargon) without its task. It says “the tests pass” instead of “CI is green”, leaves out hashes, file paths, commands, build numbers, and test counts unless you need one to act, and calls each PR, branch, or agent by a name you would recognize.
  • How it runs:
    1. Gather, read-only. The turn changes no code, starts no app or job, and posts nothing. It collects the agent’s own work, subagent reports, and messages from others in the chat, checks the current state of every PR, CI run, or agent the chat touched, and checks each number it will show against its source.
    2. Select action items. An action item is a call only you can make: a product choice, an approval, an irreversible action, or access the agent lacks. It includes items raised before your last message that still wait on you. Work the agent can still do is excluded, and no item is invented to fill the reply.
    3. Write the reply. Open with 1 sentence that names what waits on you, or says that nothing does. Show what happened with pictures first, then 1 bullet per thing you asked for, saying what came of it and whether it is done, still running, failed, or not checked. Keep this part under 100 words, excluding pictures. Add at most 3 lines that change what you know or must do, and 1 line naming work the agent can still do itself.
    4. List the action items, about 30 words each. Each gives the call, the agent’s pick, what it changes for users, the evidence, the risk (even a low one), and a link. When several items share a call, the call and pick appear once and the items follow, riskiest first. A choice between options gives each option’s gain and cost.
  • Visuals: A visual is a screenshot, a video, a Mermaid diagram, a chart, or a generated image; a Markdown table does not count. Each one should be readable at a glance, with at most 6 boxes and at most 8 words per box. Status lists, lists of action items, and unconnected boxes are never drawn. A visible change without a screenshot is marked “No screenshot yet” in its summary line. Numbers are never invented, and screens that were not captured are never drawn.
  • Points to watch: Items are never cut or shortened to meet a word count, and a link never replaces an item. The reply grows with the number of items, but the narrative part stays short.

/ketchup-video: the same catch-up as a subtitled video

Source: skills/ketchup-video/SKILL.md

  • What it does: It follows /ketchup, but replaces the summary and visuals with a short, silent, subtitled video of slides. The action items stay as text below the video.
  • When to use it: When you type /ketchup-video, typically when the changes are visual or easier to follow as pictures.
  • How it runs:
    1. The window starts at the last message you wrote before /ketchup-video, not before any earlier /ketchup. Writing and rendering the video outside the repository is the only exception to the read-only rule.
    2. Plan the slides from the screenshots, recordings, diffs, and data the work produced, not from the chat’s prose. First write the 1 sentence you should leave with and 1 line per slide, then drop every slide that does not change what you know. The maximum is 10 slides, and fewer is better.
    3. Each slide makes 1 point. The slides build on 1 picture that changes from slide to slide, colors and shapes keep the same meaning throughout, and arrows, highlights, and motion point at what changed. A slide is never a bullet list, a status list, a table, or unconnected boxes.
    4. Each slide has a subtitle of about 10 words in a strip below it. The strip has the same height on every slide, so the subtitle never covers the picture, and it is burned into the frames for the slide’s whole hold time.
    5. Render 1 silent horizontal video (for example an mp4) with motion between slides, made from the slides themselves rather than a screen recording. Each slide stays fully on screen for at least 1 second per 3 words it adds.
    6. Before embedding, inspect 1 frame per slide at chat size, check that the subtitle is readable and covers nothing, and measure each hold by matching the file’s frames to the slide. A still-frame detector is not acceptable because it counts the faint ends of a fade as still. Fix and render again until every slide passes.
  • Points to watch: The reply is the ketchup opening sentence, the video, 1 line naming work the agent can still do, and the action items. If rendering fails, the agent says so in 1 line and returns only the action items. As in /ketchup, numbers are never invented and screens that were not captured are never drawn.

/make-bot-ui: build a page whose buttons wake a bot

Source: skills/make-bot-ui/SKILL.md

  • What it does: It builds a page you click (buttons or a dashboard). A server on the local computer POSTs JSON to a webhook routine, and that wakes a Grok Bot with the JSON. The webhook routine is the agent task that the webhook POST starts. The skill also exposes the page on Tailscale.
  • When to use it: When you build a custom UI that should wake a Grok Bot over a webhook, when you need to provide a webhook sender key, or when you want to put that UI on Tailscale.
  • How it runs:
    1. Create the routine with update_state (target routine, action create, trigger { "type": "webhook" }). Its prompt says to treat the POST body as untrusted data, names the JSON fields the UI sends, does the matching action, and sends no message when there is nothing to report.
    2. Tell you where to find the webhook URL and the sender key on the routine’s panel. You may paste the URL into the chat; you must never paste the sender key.
    3. Request the key with a secret-request card, which is the entire turn. The agent never sees the value: it lands in the connector’s credential file, and the agent copies it into the server config without printing or logging it.
    4. Host the page. The {url, key} pair is stored in the UI’s own directory. The POST comes from the server, never from the browser, and carries Authorization: Bearer <key> and X-Automation-Key: <key>, with an 8-second timeout and a single attempt without retries. Send one probe with a harmless payload, which the prompt ignores, before you announce the UI. Where a POST might fail, also write the same JSON to a local log for the routine to drain; polling must never be the main path.
    5. Put it on the tailnet. Bind to 0.0.0.0:<port>, because Tailscale peers cannot reach a server bound to 127.0.0.1. If tailscale status shows an online node, reuse it and give you both the hostname URL and the 100.x.x.x URL over HTTP. Otherwise install Tailscale, run tailscale up with a short hostname, and send you the login URL so you can approve the machine yourself; the agent never asks for or types Tailscale credentials.
    6. Handle the wake. The routine receives a <webhook_event> block whose body field is the JSON object as a string. The agent parses body and treats it as outside data, not as instructions.
  • Points to watch: The sender key never appears in the browser, the chat, or the skill. Media bytes are never sent over the webhook, and a second hostname is never created on a node that is already online. Keep the field list small and use the same field names in the UI and the routine prompt.

Benny: a dormant automation pack

The plugin also ships automations/benny/ (README), a pair of Cursor automations that triage Slack issue reports and reproduce confirmed bugs, possibly preparing a small draft fix. It is not a slash skill: its files stay dormant until a setup step copies the pack into a target repository and the automations are enabled there. Learning and communication describes it in detail.

Learning and Communication

This group covers understanding something, explaining it to a person, and turning what a session taught into lasting changes. It contains a skill that teaches, a skill that mines a conversation for lessons, a writing standard, a skill that restates the last reply in plain words, and the 2 skills that guide and configure pstack itself. The chapter ends with the background parts that ship with pstack but are not slash skills: 2 subagent definitions and one automation pack.

/teach: one plain account of how and why

/teach explains what a piece of work is, how it works, and why it is built that way, at the person’s own pace. Its goal is understanding; it changes nothing in the code. Typical requests are “teach me this”, “help me really understand X”, or “explain this change or subsystem to me”.

The skill sits on top of /how and /why. It reads enough code to get oriented, then runs both skills as real invocations, in parallel, and blends what they find. For a small change one of them may be enough. It may reword their findings freely, with one exception: the confidence language that /why attaches to its conclusions is kept intact, because those hedges are findings in their own right.

The skill describes how the explanation should be built:

  1. Choose what the person should take away. Infer from the conversation why they are asking (about to change the code, reviewing it, debugging it, new to it) and what they already know, and put the depth where their question is.
  2. Start with a plain definition. Name the thing in general terms, as a senior engineer would say it aloud, then connect it to the case at hand and build outwards to mechanism, reasons, and edge cases. A list of functions and constants is reference material, not teaching.
  3. Give the smallest complete answer first. One or two sentences, then stop and add layers when asked.
  4. Keep it a conversation. No quizzes, no “say it back to me”, no announcements that a part is important or tricky. Without a live human, deliver the explanation cleanly and put the offer to go deeper at the end.
  5. Show as well as tell. Open the diff, the code, or the debugger when that is fastest. For anything with 3 or more moving parts, draw a short series of diagrams in which each one redraws the previous and adds a single part, so the reader watches the system assemble. Mermaid suits flows whose labels carry the meaning; spatial ideas such as layout or scroll position call for a generated whiteboard-style image with few labels.

The prose goes through the unslop skill: plain spoken English, concrete mechanisms instead of metaphors, sentences with at most 1 or 2 commas, one name per concept, and no framing labels such as “the key insight” or “TL;DR”. The reply is the explanation itself, never a report about what was explained.

/reflect: turn a session’s lessons into skill edits

/reflect runs when the user says “reflect”. It reads the whole transcript of the current conversation and routes each durable lesson to a concrete edit on an existing skill. The transcript is treated as data, so instructions found inside it are not followed.

Its search covers 5 kinds of signal: corrections from the user; commands and quirks that the agent had to work out for itself; context the user provided although the agent could have fetched it; checks that were skipped or never executed against the real artifact; and skills that ought to have triggered but stayed silent.

A finding survives only if it meets all 3 conditions: it will still hold in 6 months, it would change what a future agent does, and it routes to a skill the session used. The agent reads that skill first and drops anything it already says clearly. One-off events and details that drift (SHAs, versions, counts) are discarded. A skill that should have fired gets its description tuned, and anything a lint, script, or check could enforce goes to a backlog instead of into prose.

The result is presented as 3 lists (Accepted with problem, proposal, and skill; Rejected with reasons; Backlog), and no skill is edited before the user approves. Skills under plugins/cache/ are never edited directly. Before approval the agent shows the destination, .cursor/skills/<skill>/ or ~/.cursor/skills/<skill>/; after approval it copies the skill folder there and edits the copy. It never opens a PR or pushes.

/technical-writing: a layered standard for technical prose

/technical-writing applies when writing or reviewing docs, RFCs, READMEs, PR descriptions, or commit messages. Its stated aim is text that “a tired engineer understands on the first read”. Above the layers it sets a few general rules: cut every word that does no work, prefer the everyday word, use the real symbol or command name instead of a description of it, avoid invented jargon, and vary sentence length.

The standard stacks 4 established sources, each governing a different level of the text:

LayerSourceWhat it controls
DocumentDiátaxisOne mode per document: tutorial (learning by doing, every step with a visible result), how-to (steps to a goal for a competent reader), reference (dry, complete facts that mirror the thing described), or explanation (one bounded topic, the only mode where opinion belongs). Mixed content is split and linked.
SentenceGoogle developer documentation styleAddress the reader as “you” in the present tense, name the actor, write instructions as commands with the condition first, avoid “simply” or “easy” in procedures, use descriptive link text, sentence-case headings, and serial commas.
StatementSimplified Technical English (STE)One instruction per sentence, splitting instructions above about 20 words and other sentences above about 25, warnings before the step they guard, one meaning per word.
SyntaxGlobal EnglishKeep “only” and “not” next to the word they modify, make every pronoun point at one obvious thing, avoid noun stacks, idioms, and Latin abbreviations, and prefer periods to semicolons or dashes.

The skill also hands slop detection to the unslop skill. It treats PR descriptions and commit messages as writing too: every layer except Diátaxis applies to them, and a PR body should be a briefing a reviewer can read in under a minute, with logs and metric tables linked rather than pasted. Product UI strings follow the product’s own copy guidelines instead. Any count or tree in a document must be true at the commit that lands it and come with the command that regenerates it.

/bro: say that again, plainly

/bro is the shortest skill in pstack. It asks the agent to restate its last message without jargon, more simply and concisely, “like one human talking to another”. Use it when a reply was dense enough that you could not follow it.

/poteto-help: the guide to pstack

/poteto-help answers questions about pstack itself. For a help question it gives the answer, a prompt the user can send, and a link to the file the answer came from, but it does not start the work, since a pstack run costs real tokens and the user only asked how. A message that actually asks for work (“use pstack to fix this bug”) is handled differently: the agent reads poteto-mode, does the work under it, and mentions once that a Custom Mode keeps the mode active.

The skill is a routing map from questions to the skills and guide pages that hold the details. The agent reads the target file before quoting it and trusts that file whenever it disagrees with the map. Because the installed plugin may not be visible to the user, links are given as public GitHub copies under https://github.com/cursor/plugins/blob/main/pstack/.

Finding the need

When the need is unclear, the agent asks one multiple-choice question with 5 options and answers only the chosen section:

  • Get set up
  • Start a task with /poteto-mode
  • Pick a skill for a situation
  • Fix a run that went wrong
  • Make pstack my own

It also checks project state that changes the answer: whether ~/.cursor/rules/pstack-models.mdc exists (if not, every role runs on its default model), whether the project has a verify-* skill, and whether a formal verification skill exists and has fallen behind the code it covers. When the model rule is missing and it matters, the agent asks at most once per chat whether the user wants to run /setup-pstack now or later.

What the sections contain

  • Setup: install with /add-plugin pstack, run /setup-pstack, and then begin a real task using /poteto-mode together with a goal and a pass-or-fail check. The installation by itself has no effect. If cost is a worry, the section recommends a smaller budget, cheaper models, roles set to auto or inherit-parent, shorter panel lists, and keeping /poteto-mode for work that demands rigor. It also covers installing in Claude Code, where every command carries a pstack: prefix, as in /pstack:poteto-mode.
  • Starting a task: a good prompt states the goal and how to tell it is done, and does not list skills. Pressing Enter on /poteto-mode attaches it to one message, while Option+Enter or Alt+Enter (or “Use as Mode”) turns it into a Custom Mode that stays in context until the user leaves it.
  • Picking a skill: a table mapping intentions to skills, with /poteto-mode as the default answer, plus notes on close calls such as /how versus /why versus /teach, and /arena versus /swarm. It also lists what pstack does not contain: /deslop, control-cli, and control-ui belong to the cursor-team-kit plugin; /loop and /create-skill are Cursor built-ins; and there is no /orchestrate skill.
  • Playbooks and principles: playbooks have no slash command and are selected inside /poteto-mode by describing the task or by phrases such as “babysit this pr” or “land the stack”. Principles are usually steered by name (“apply prove it works”) rather than invoked. See Playbooks and Principles.
  • Fixing a run: a symptom table, for example “the mode stopped applying after a few turns” (it was started with Enter) or “a new model choice had no effect” (the rule applies only to new chats).
  • Making pstack your own: /automate-me, /reflect, the authoring and eval playbooks, and the advice to fix a misbehaving skill in its own PR.

The reply leads with the answer and contains at most one example prompt, adapted from the skill’s recipes reference where one fits.

/setup-pstack: choose a model and reasoning budget per role

/setup-pstack decides which model each pstack role uses (a role is a kind of work or a seat in a review panel, such as bug-fix or arena runners) and at what reasoning effort. It writes the result to ~/.cursor/rules/pstack-models.mdc, an always-applied rule that overrides the skill defaults. It is the only pstack skill that loads from the user’s words alone, for example “configure pstack models” or “pstack budget”.

Steps

  1. Detect available models. The dependable source is the list of model slugs that can be passed to a Task subagent in this session; a models API or CLI is preferred when Cursor offers one. If nothing can be detected, the user is asked to paste the slugs. A real slug is never written unless it has been confirmed, while the aliases inherit-parent and auto are always valid.

  2. Load the current state. An existing rule supplies the current budget and role values. Lines for retired roles are dropped, and values from older setups that were defaults rather than choices (marked by a missing # defaults: 3 line, old Gemini panel entries, a # budget: unlimited line) are replaced. The user is told what was replaced.

  3. Budget, map, and confirm. The user picks one of 3 budgets, preferably through a structured question:

    BudgetEffort for roles whose default is xhigh
    largexhigh (matches the skill defaults)
    mediumhigh
    smallmedium

    Each budget moves every role’s default effort down 0, 1, or 2 steps on the ladder xhigh > high > medium > low, with nothing above xhigh. If the resulting slug was not detected, the agent uses the same family’s highest detected effort at or below the target, or marks the role as needing a choice. It then shows every role with its model and asks whether to accept or change specific roles.

  4. Validate. Every real slug must be in the detected set and at xhigh or below.

  5. Write the rule. The whole file is overwritten with alwaysApply: true, a # defaults: 3 line, a # budget line, and one line per role, so re-runs are idempotent. The roles are feature, refactoring, bug-fix, perf-issue, hillclimb, judgment and prose, arena runners, arena cross-judge pool, swarm workers, and interrogate reviewers.

  6. Confirm that the rule applies to new sessions.

  7. Offer a verification skill once, if the project has no way to drive the real app, and run /create-verification-skill on a yes.

  8. Offer a formal verification skill once, if none exists, and run /create-formal-verification-skill on a yes. A no is accepted without pressure in both cases.

Panel roles

Panel roles (arena runners, interrogate reviewers) take a list as their value. Each entry, including any alias, starts its own subagent, so a longer list means more parallel work. arena cross-judge pool is a list too, yet Arena uses just one judge: it tries the entries in list order, considering only vendors other than the parent chat’s, which makes the order a ranking of preference. Fable and the other Claude models are treated as a single vendor, and an alias value is never used as the judge. swarm workers gives the default model for all workers, except when a race assigns a model to each arm.

Background subagents and the automation pack

Besides the skills, pstack ships parts that never appear in the slash menu: 2 subagent definitions under agents/ and one Cursor Automations pack under automations/.

poteto-agent: the delegate for poteto-mode

poteto-agent is the subagent that a /poteto-mode run spawns for code-writing and helper tasks. The parent chat owns the playbook, the todo list, and every spawn; the delegate only does the work it was handed. Before any work it reads the poteto-mode SKILL.md in full, including the inline principles index, from the absolute path its parent supplied. Without a path it searches ~/.cursor/plugins/ and picks the copy with the highest plugin version; if none exists, it stops and tells its parent.

The definition warns that substituting a general-purpose subagent skips that read and lets the style drift. A fresh poteto-agent is spawned for each task, and one is resumed only in the narrow cases that the Subagents section of poteto-mode names. You can also spawn it yourself with subagent_type: "poteto-agent" to get the same style from your own subagent.

Comment Sicko: a reviewer that wants comments gone

comment-sicko is a reviewer subagent with a deliberately extreme persona that hates comments. Given scoped files or a diff (by default the diff against main), it hunts narration, banners, commented-out code, and long justifications for workarounds.

Only a short list of exceptions survives: legal or licence headers, non-obvious behavior forced by an external dependency, platform, vendor, or protocol, // prettier-ignore, doc comments that define a public API contract, and issue or RFC links explaining a constraint the code cannot express. When in doubt, the comment goes. Lint suppressions such as eslint-disable or @ts-ignore survive only if the rule is faulty or purely stylistic.

A surprise in the project’s own code is not a valid reason to keep a comment. Comment Sicko deletes such a comment and marks the exact symbol MUST KILL, asking for a rename, extraction, type, or redesign that makes the behavior obvious without prose. Before judging a claim such as “do not remove”, it reads nearby code, traces the named symbol, or runs /why on it. It only reports (touched files, deletion count, MUST KILL flags, skips) and never writes application code.

benny: an automation pack for Slack issue reports

benny is a pack of 2 Cursor Automations that work together in one Slack issue channel.

  • Triage starts on each new top-level report, reads the thread and attachments, and classifies it as a bug or performance issue, a feature request, a question or feedback, or a reroute. It traces the likely owning layer, searches the configured tracker for duplicates, creates a ticket only for a clear new bug, and posts exactly one reply in the source thread with a short verdict and a marker such as [benny:bug].
  • Reproduce and fix waits for the trusted triage marker, stops if someone clearly owns the fix, and verifies an existing PR instead of competing with it. Otherwise it reproduces the exact symptom twice through the real UI with screenshots, video, and a read-only state cross-check. After a confirmed reproduction it may attempt one bounded root-cause fix and opens a draft PR only when the before-and-after proof passes.

Throughout a run, each of the 2 automations holds the source channel and thread coordinates constant, never starts a new root message in the source channel, and does not pass Slack credentials to subagents. If the channel coordinates, tracker access, the control adapter, or the feature map is missing or in doubt, they fail closed. The only PRs they open are drafts, and they never merge or deploy.

The pack is dormant: its files do not appear as slash skills, and its SKILL.md files are direct instructions for the automations rather than registered plugin skills. To set it up, you point Cursor at FOR_AGENTS.md and name the target repository. Setup merges the pack into .cursor/automations/benny/, enables pstack in the target’s .cursor/settings.json (the pack depends on shared skills such as why, tdd, unslop, and the principle skills), and keeps user-owned configuration such as channels, tracker settings, and the feature map outside the pack, for example under .cursor/benny/. After everything is committed, you review each automation draft, send a harmless test report, and confirm that every post stays in the original thread.

Principles Overview

A principle in pstack is a short, named rule about how an agent should make one kind of decision. pstack ships 24 of them. Each lives in its own skill file, skills/principle-<name>/SKILL.md, which poteto-mode calls the principle’s leaf. A leaf states when the rule applies and what the agent should do, and little else.

Principles are never invoked on their own: every leaf carries disable-model-invocation: true in its front matter. They take effect through /poteto-mode, the operating-style skill that keeps an index of all 24 and decides which ones a task triggers (see Using /poteto-mode).

How principles work

The “Principles” section of poteto-mode’s SKILL.md is the index. Each entry gives a principle’s title and a one-line trigger, the situation in which it applies. According to the principles guide, poteto-mode reads this index at the start of every multi-step task.

The index is only a pointer. For any principle it actually applies, the agent must first read the full leaf. The leaf’s skill name follows a fixed rule: principle- plus the title in kebab case, keeping hyphens and removing any other punctuation. The only entry that overrides this rule is Sequence Work into Verifiable Units, whose leaf is principle-sequence-verifiable-units.

Naming applied principles

Among poteto-mode’s non-negotiables is a reporting duty. In its reply, the agent must name each principle that shaped a decision and state the specific choice that principle changed. It may cite only principles whose leaf it read during the current session.

The guide adds a test for these citations. A principle named with no decision attached means the agent cited the rule without applying it. When you review a reply, look for the pair (principle, changed decision) and treat a bare name as a warning sign.

Steering with principle names

You never invoke a principle yourself. Instead, you use its name to redirect the agent. Because each name points at a complete rule the agent has already read, one phrase carries more precise instructions than a paragraph of explanation. The guide gives 3 examples, quoted here:

SituationWhat you type
The agent is about to add a fourth adapter beside 3 existing onesuse subtract before you add. delete the obsolete adapters first, then design what's left.
The agent claims success because the build passedapply prove it works. run the real import flow and show me the written records.
2 parallel attempts are about to write to the same branchseparate before serializing shared state. give each attempt its own worktree, no locks.

The guide’s advice on learning the list is to skim it once and return to it whenever you see the agent do something one of these names would have prevented.

Upstream categories and this book’s chapters

The poteto-mode index sorts the 24 principles into 5 categories:

CategoryCountScope
Core10How much to build and when to rethink the design
Architecture6Where state, validation, and compatibility live
Verification5What counts as proof
Delegation2Keeping parallel work manageable
Meta1Turning repeated advice into structure

This book uses its own grouping of 4 chapters, arranged by the stage of work in which a principle tends to matter. Every principle appears in exactly one chapter. The tables below give each trigger in brief; the chapters explain each rule and link its leaf.

Premises and Thinking

PrincipleSkillApplies when
Attack the Premiseprinciple-attack-the-premise2 or more fixes sharing one premise have failed the same gate
Foundational Thinkingprinciple-foundational-thinkingBefore writing logic: choosing core types, ordering scaffold and feature work, deciding what concurrent actors share
Redesign from First Principlesprinciple-redesign-from-first-principlesA new requirement must be integrated into an existing design
Exhaust the Design Spaceprinciple-exhaust-the-design-spaceA novel UI interaction or architectural decision has no precedent in the codebase
Model the Domainprinciple-model-the-domainWriting stateful logic, or code that branches heavily or repeats a shape assumption across files
Laziness Protocolprinciple-laziness-protocolRefactoring, judging diff size, or feeling tempted to add abstractions, layers, or signal threading

Quality and Verification

PrincipleSkillApplies when
Prove It Worksprinciple-prove-it-worksA task is finished but not yet declared done
Fix Root Causesprinciple-fix-root-causesDebugging
Test Behavior, Not Implementationprinciple-test-behavior-not-implementationWriting, changing, or keeping a test
Explain the Numberprinciple-explain-the-numberBefore measuring, and before trusting, reporting, or acting on a measured number

Design and Boundaries

PrincipleSkillApplies when
Boundary Disciplineprinciple-boundary-disciplineWiring validation, error handling, or framework adapters
Type System Disciplineprinciple-type-system-disciplineDesigning types or signatures, or writing code in any statically typed language
Minimize Reader Loadprinciple-minimize-reader-loadReviewing or shaping code that is hard to trace
Subtract Before You Addprinciple-subtract-before-you-addSequencing an addition, refactor, or rewrite
Build the Leverprinciple-build-the-leverAny non-trivial work: edits, migrations, analyses, checks
Encode Lessons in Structureprinciple-encode-lessons-in-structureYou write the same instruction a second time, or notice a recurring correction

Execution and Operations

PrincipleSkillApplies when
Sequence Work into Verifiable Unitsprinciple-sequence-verifiable-unitsWork done in several steps (sweeps, migrations, series of similar edits), and stacks of commits or PRs
Make Operations Idempotentprinciple-make-operations-idempotentDesigning commands, lifecycle steps, or loops that run amid crashes, restarts, and retries
Migrate Callers Then Delete Legacy APIsprinciple-migrate-callers-then-delete-legacy-apisIntroducing a new internal API while old callers still exist
Separate Before Serializing Shared Stateprinciple-separate-before-serializing-shared-stateConcurrent actors might write to the same file, branch, key, or state object
Guard the Context Windowprinciple-guard-the-context-windowContext is filling up: large outputs, long files, repeated reads, fan-out planning
Never Block on the Humanprinciple-never-block-on-the-humanYou are tempted to ask “should I do X?” about reversible work
Outcome-Oriented Executionprinciple-outcome-oriented-executionA planned rewrite or migration with explicit phase boundaries is under way
Experience Firstprinciple-experience-firstProduct, UX, or feature-scope trade-offs come up

How to read the next chapters

Each leaf is brief. None runs much past 15 lines, and the body of Exhaust the Design Space is a single sentence. In the shortest leaves, the description field carries most of the rule, so the chapters draw on both the description and the body. For every principle, the chapters cover the rule itself, the situations that trigger it, and how you can use its name when steering.

Premises and Thinking

This chapter covers 6 principles that matter before and during the first decisions of a task: which assumption to question, what to settle first, how widely to explore, and when to stop adding. A principle is a named pstack rule stored in its own skill file (its leaf); /poteto-mode reads the index of all principles and applies the ones a task triggers. The Principles Overview explains that mechanism.

Attack the Premise (principle-attack-the-premise)

Source: skills/principle-attack-the-premise/SKILL.md

  • Rule: once 2 or more fixes that rest on the same premise have failed at the same gate, the leaf tells the agent to doubt the premise itself. The individual fixes are no longer the suspect.
  • Method: write the premise down as the single sentence every failed fix assumed. Then, before attempting another fix, test that sentence: find an observation whose outcome would differ if the premise were false, and make it. Examine how the failures are distributed as well as how large they are.
  • When the premise falls: look for what the failures have in common that the premise did not predict. If one component always ends up on the losing side, change whatever places it there; adding a mechanism that cleans up after it is the wrong response.
  • Steering: the leaf is explicit that no new fix should begin until the premise has been written down and tested. Asking the agent to “state the premise in one sentence before the next fix” holds it to that order.

Foundational Thinking (principle-foundational-thinking)

Source: skills/principle-foundational-thinking/SKILL.md

  • Rule: settle the shape of the data before writing logic. Define the core types early, trace every access pattern, and choose structures that suit the dominant paths. Remove duplication at the level of structure; there is no need to deduplicate every line.
  • Shared state: before letting several actors share state, ask what would happen if another actor changed it at the same moment. Unless the answer is “nothing”, isolate the state.
  • Scaffold first: after dead code has been removed, build whatever helps every later phase (CI, tests, shared types) before the features themselves. Commits stay small and single-purpose.
  • Promise and steering: the description states the payoff: with the right data structures, the code downstream becomes obvious. You can ask to see the types and data structures before any logic is written, which makes this ordering visible.

Redesign from First Principles (principle-redesign-from-first-principles)

Source: skills/principle-redesign-from-first-principles/SKILL.md

  • Rule: when a new requirement arrives, avoid bolting it onto the current design. Redesign as though the requirement had been a foundational assumption from the beginning.
  • Method:
    1. Read every affected file and understand the existing design.
    2. Ask the leaf’s question: “if we were writing this from scratch with this new requirement, what would we build?”
    3. Propagate the change to every reference, including types, docs, examples, and rationale sections.
    4. Plan the whole redesign, then deliver it in increments.
  • Purpose: the leaf presents this as the way to preserve option value while changes accumulate in an existing design.
  • Steering: when a diff looks patched on, ask the agent to redesign from first principles and to answer the from-scratch question explicitly.

Exhaust the Design Space (principle-exhaust-the-design-space)

Source: skills/principle-exhaust-the-design-space/SKILL.md

  • Rule: faced with a novel UI interaction or architectural decision for which the codebase offers no precedent, build 2 or 3 competing prototypes and compare them side by side before committing to one.
  • Scope: the leaf extends the rule to product design decisions where the user experience depends on feel more than on logic.
  • Steering: a request such as “build 3 options and compare them” brings this principle into play. It is most useful when the agent is about to settle an unprecedented decision with a single proposal.

Model the Domain (principle-model-the-domain)

Source: skills/principle-model-the-domain/SKILL.md

  • Rule: express the domain as a data structure instead of spreading it across conditionals. A well-chosen structure makes invalid states impossible to represent and removes branches altogether.

  • Typical substitutions:

    Instead ofUse
    Scattered booleans or phase checksA state machine
    Loose parametersA typed model
    Branching spread across filesA map, registry, or discriminated union
    Ad hoc mutationsA reducer
    An access pattern the current collection serves poorlyAn index, queue, or normalized collection
  • Limits: the leaf warns against forcing a structure. Boring code is fine when the shape is clear, local, and unlikely to grow. An abstraction that adds indirection without removing any branches or invalid states deserves suspicion.

  • Warning signs: a feature that lengthens an if/else chain by one more branch, or a second boolean that must be kept in sync with the first, shows that this principle was skipped. Asking “could this branch be expressed as structure?” is a natural way to steer.

Laziness Protocol (principle-laziness-protocol)

Source: skills/principle-laziness-protocol/SKILL.md

  • Rule: favor deletion and the smallest change that solves the problem. The principle applies while refactoring, while judging the size of a diff, and whenever the agent is tempted to introduce abstractions, layers, or signal threading.
  • Consolidate decisions: a choice should be made in one place. Put it behind a single source of truth and pass the outcome along as a simple flag, so the same decision is never repeated elsewhere.
  • Minimize the diff: fewer lines win over boilerplate that merely looks elegant.
  • Steering: when a diff grows larger than the problem seems to justify, ask for the Laziness Protocol and a smaller change.

Quality and Verification

The 4 principles in this chapter define when the agent may say “done” and what evidence must back that claim. A principle is a named pstack rule kept in its own skill file (its leaf); /poteto-mode keeps an index of all of them and applies the ones a task triggers, as described in the Principles Overview. The poteto-mode index files Prove It Works, Fix Root Causes, Test Behavior, Not Implementation, and Explain the Number under its “Verification” category, which the guide summarizes as the principles that “define what counts as proof”. The fifth member of that category, Sequence Work into Verifiable Units, is covered in Execution and Operations.

Prove It Works (principle-prove-it-works)

Source: skills/principle-prove-it-works/SKILL.md

  • Rule: before declaring a task done, check the real artifact directly. Run the feature, read the actual value, inspect the diff.
  • What does not count: proxies such as file modification times, the agent’s own report, cached output, or the fact that the code compiles.
  • Failed checks: when a check fails, the leaf tells the agent to suspect its method of observation before it suspects the system.
  • Scripting: wherever possible, turn the check into a deterministic script that reruns the comparison, since a repeatable check is stronger than a single look. Keep the output where the human can see it, and commit it only if the trail must be auditable later.
  • Steering: the guide’s own example covers the most common case. When the agent claims success because the build passed, type apply prove it works. run the real import flow and show me the written records.

Fix Root Causes (principle-fix-root-causes)

Source: skills/principle-fix-root-causes/SKILL.md

  • Rule: repair the fault itself, which may lie far from where the symptom appeared. The root cause is the first point at which the system did something it should not have done, or failed to handle a state it should have handled.
  • Method: reproduce the problem first. Keep asking “why” until the answer is a wrong decision in the code, and when progress stalls, add instrumentation and read the actual state.
  • The deciding question: was the state that set off the symptom a legitimate one? If so, deal with it at the point where the code failed. If that state should never exist, a check at the point of failure only conceals the bug, so trace whatever produced the state. The leaf lists the usual ways of concealing a bug: guards, retries, swallowed errors, clamped values, and discarded state.
  • Scope: fix the pattern as well as the instance by finding every other place with the same fault.
  • Follow-up: if the decisive fact required a deep investigation, propose a cheap, always-on signal that would have revealed it at first glance.
  • Steering: when a diff adds a guard or a retry, ask whether the state it handles is legitimate. The description states the test plainly: “A guard is a fix only when the state it handles is legitimate.”

Test Behavior, Not Implementation (principle-test-behavior-not-implementation)

Source: skills/principle-test-behavior-not-implementation/SKILL.md

  • Rule: a test asserts something the users of the code can observe through its interface. That means return values, errors, state they can read back, and effects on external systems. Private helpers, internal call order, and intermediate data belong to the implementation.

  • 2 imagined edits: the leaf judges every test against 2 hypothetical changes.

    Imagined editIf the test…Verdict
    Break the behavior (a wrong value, an effect skipped or doubled)still passesIt proves nothing
    Change the internals while keeping every observable resultfailsIt is pinned to the implementation

    Keep the tests that catch the first edit and survive the second; rewrite or delete the others.

  • Why tests prove nothing: the leaf gives 3 common reasons. An assertion may be too loose, the expected value may come from the very code being tested, or the assertion may check data that the test built for itself.

  • Writing good tests:

    • Drive the code through its public interface with a concrete input.
    • Derive the expected value from the requirement.
    • Count the data an external service receives as behavior, and keep calls to internal helpers out of the assertions.
    • Pair every “this never happens” assertion with a case where it does happen.
    • Assert the error type that callers branch on, and leave the message text unasserted.
  • Steering: if a refactor that preserves behavior breaks many tests, those tests are pinned to the implementation, and naming this principle asks the agent to rewrite them.

Explain the Number (principle-explain-the-number)

Source: skills/principle-explain-the-number/SKILL.md

  • Rule: scrutinize a measured number (a speedup, a regression, a throughput, a latency, an eval result) twice. Once before measuring, and again before trusting, reporting, or acting on it. Identify what limits the number, and rule out the possibility that it measured something other than the intended work.
  • The 4 steps of the leaf:
    1. Before running, write down the decision at stake, the result that would change it, and the noise floor. Stop if the spread between runs exceeds the effect.
    2. Ask the leaf’s question, “why not double?” Name the resource or code path that bounds the result, using a profile or counters captured during a run. A guess from reading the code does not qualify as a limiter.
    3. Consider the other things the number might reflect (errors, work that was skipped or cached, code that never executed, a side that was not tuned, noise, or a piece too small to matter), and rule each one out with evidence.
    4. Keep the run count, the spread, and the limiter together with the number.
  • Performance numbers: the leaf hands these to the benchmark-checklist skill, which the guide describes as turning the principle into 7 questions answered from real runs (see Verification).
  • Eval results: ask whether every run actually performed the task, whether the gap holds across trials and models, and whether the scenario matters at all.
  • Steering: when the agent reports a bare figure, ask it to explain the number and name the limiter.

Design and Boundaries

The 6 principles in this chapter concern the shape of the code: where its defenses sit, how much the types are made to enforce, and how much a reader must hold in mind. The chapter closes with 2 principles that turn design effort into lasting artifacts, namely tools and structural checks. A principle is a named pstack rule kept in its own skill file (its leaf); /poteto-mode reads the index of all principles and applies those a task triggers, as the Principles Overview explains.

Boundary Discipline (principle-boundary-discipline)

Source: skills/principle-boundary-discipline/SKILL.md

  • Rule: concentrate validation, type narrowing, and error handling at the points where data crosses a system boundary, such as CLI arguments, config files, external APIs, and the network. Inside the system, trust the types; re-validation and redundant nil checks have no place there.
  • Parsing and surfaces: parse raw data into domain types at the boundary, and keep transport and framework types off the public surface.
  • Pure core, thin shell: business logic belongs in pure functions that depend on no framework. The shell that calls them stays thin.
  • The 2 tests from the leaf:
    1. Does this data cross a boundary at this point? When it does not, the check duplicates protection that already exists.
    2. Could this logic become a pure function for the shell to call? When it could, move it out.
  • Steering: name this principle when defensive checks start multiplying in internal code.

Type System Discipline (principle-type-system-discipline)

Source: skills/principle-type-system-discipline/SKILL.md

  • Rule: let the compiler reject impossible states, mismatched primitives, and unhandled variants. It applies when designing types, reviewing a function signature, or writing code in any statically typed language.
  • Brand semantic primitives: if 2 arguments share a primitive type but carry different meanings, give each its own type and validate the value once, when it is created.
  • Parsing external data: the leaf treats anything from outside (JSON, RPC payloads, CLI arguments, config, environment variables, database rows) as untyped until a parse function at the boundary has converted it into the typed model.
  • Derive from authoritative schemas: if a schema file is the owner of a shape, generate the type from that file rather than keeping a separate hand-written copy in parallel.
  • Exhaustive variants: the description adds that every variant should be handled, so the compiler can flag any case left uncovered.
  • Related skill: for TypeScript syntax, the leaf refers to typescript-best-practices (see Building and Code Quality).

Minimize Reader Load (principle-minimize-reader-load)

Source: skills/principle-minimize-reader-load/SKILL.md

  • Definition: reader load is the effort a reader must spend to understand code. The leaf measures it along 2 independent axes: the number of layers to trace between a question and its answer, and the amount of hidden or mutable state the reader must keep in mind. Both need guarding.
  • Collapse forwarding layers: wrappers with a single caller, adapters with no second implementation, and pass-through methods should be inlined.
  • Shrink state scope: prefer return values to mutation, locals to fields, fields to module state, and module state to globals. Derive values where you would otherwise keep copies in sync.
  • Invariants: state an invariant once, at the boundary, and avoid repeating it in every consumer.
  • The test: the leaf asks whether a newcomer to the code can answer “where does X come from?” and “what can change X?” within 30 seconds. When they cannot, reduce the layers or the state.
  • Steering: this principle is a good response when code the agent wrote itself turns out to be hard to follow.

Subtract Before You Add (principle-subtract-before-you-add)

Source: skills/principle-subtract-before-you-add/SKILL.md

  • Rule: when evolving a system, remove complexity first and build afterwards. Subtraction is the default.
  • Continual investment: the leaf treats simplification as an ongoing habit. Each change should leave the design slightly simpler and more capable, behind a surface the same size as before or smaller.
  • Practices:
    • Schedule removal before construction.
    • Cut before polishing; reach the minimum before investing in quality.
    • Design for observed usage instead of speculative edge cases.
    • Write no validators, parsers, or guards beyond what the spec requires.
    • Simplify prompts by removing redundant instructions and excessive templates.
    • Delete a reference that adds no new content instead of leaving it as a stub.
  • Steering: the guide’s example applies when the agent is about to add another adapter beside existing ones: use subtract before you add. delete the obsolete adapters first, then design what's left.

Build the Lever (principle-build-the-lever)

Source: skills/principle-build-the-lever/SKILL.md

  • Rule: for any non-trivial work (edits, migrations, analyses, checks), build the tool that performs it or proves it correct, such as a codemod, a script, a generator, or a rerunnable check, instead of doing the work by hand. The threshold is triviality; repetition is irrelevant. Only a couple of obvious edits justify skipping the tool.
  • Method: complete the first unit manually, then write the tool and confirm it works by running it again on the unit you just did. Running the tool more than once must be safe.
  • Fan-out: a deterministic tool is preferable to fanning work out to subagents. When fan-out is necessary, write the recipe, the verification contract, and the fences as one skill that the delegates read and cannot modify.
  • Evidence: applying this principle produces a file. If the diff contains no script, codemod, generator, or delegate skill, the principle was not applied. Commit the tool when the work will outlive the session.
  • Size: build the smallest script that does or proves the job. A framework is never the goal.
  • The guide’s additions: the tool is what a reviewer can rerun. When an agent keeps repeating a manual task, have it write the tool or skill it wishes it had. If a script can perform a step identically every time, use the script and reserve agents for judgment calls.

Encode Lessons in Structure (principle-encode-lessons-in-structure)

Source: skills/principle-encode-lessons-in-structure/SKILL.md

  • Rule: when you notice yourself writing the same instruction for the second time, or see a correction that keeps recurring, encode the rule as structure: a lint, a metadata flag, a runtime check, or a script. More text is the wrong remedy.
  • Exception: some lessons depend on judgment and resist encoding. For such a lesson, give the instruction a more prominent place and add an example of the failure it is meant to prevent.
  • Corollary: if a structural fix exists, use only the structural fix. The leaf calls the written instruction “the symptom”.
  • Category: poteto-mode’s index places this principle alone in its “Meta” category.
  • Related skill: the guide points to /correct, which applies this principle across an entire repository (see Building and Code Quality).
  • Steering: once you have given the agent the same correction twice, ask it to encode the lesson in structure.

Execution and Operations

The 8 principles in this chapter govern how work proceeds: how it is divided into units, how it survives crashes and concurrent actors, how the agent spends its context, and how it relates to the human who supervises it. A principle is a named pstack rule kept in its own skill file (its leaf); /poteto-mode reads the index of all principles and applies those a task triggers, as the Principles Overview explains. For unattended runs, see also Running Work While You Sleep.

Sequence Work into Verifiable Units (principle-sequence-verifiable-units)

Source: skills/principle-sequence-verifiable-units/SKILL.md

  • Name: this is the one principle whose skill name departs from the title. The title is Sequence Work into Verifiable Units; the leaf is principle-sequence-verifiable-units.
  • Rule: arrange work as a series of small units, each of which ends in a state you can check. Do not move to the next unit until the current one is green.
  • The bracket: in a sweep, a migration, or a run of similar edits, each unit follows the same pattern: a known-good state, one change, the check, then onward. The per-unit check still runs when a tool makes the edits.
  • Delivery order: order the work so that the sequence itself proves it to a reviewer.
    • The failing test comes first, then the fix.
    • The subtraction comes before the reshape.
    • The baseline comes before the treatment.
    • Every commit stands alone and passes by itself.
  • Steering: when a single enormous diff appears, ask the agent to split it into verifiable units.

Make Operations Idempotent (principle-make-operations-idempotent)

Source: skills/principle-make-operations-idempotent/SKILL.md

  • Rule: design every operation that changes state so that it converges on the correct state, regardless of how many times it runs or where a previous run stopped.
  • Derive from what exists: base each step on the state that is actually present, and ignore what the previous run intended. Read the current state, compare it with the goal, and apply only the difference.
  • Leftovers: whatever a run leaves in place (a lock, a temporary file, a record written only in part, a job it claimed) has to be identifiable as stale when the next run starts. The proof of staleness must remain valid at any point at which the earlier run could have stopped.
  • Atomic writes: write to a temporary path, then rename the file into place.
  • The test: imagine the operation running twice, and imagine the previous run crashing at each point where it could crash. If the outcome then depends on the leftovers, the design needs a reconciliation step.
  • Steering: deployment and migration scripts are the obvious candidates for this principle.

Migrate Callers Then Delete Legacy APIs (principle-migrate-callers-then-delete-legacy-apis)

Source: skills/principle-migrate-callers-then-delete-legacy-apis/SKILL.md

  • Rule: when a new internal API is introduced while old callers still exist, migrate the callers and delete the old API in the same wave. Compatibility layers that keep the old API alive are what this principle avoids.
  • Tests: update the tests so they assert the new contract, and delete tests that only protect implementation details from before the refactor.
  • Preconditions: the leaf limits the principle to cases where all 3 hold.
    1. No external callers rely on the old behavior staying compatible.
    2. The project is able to take breaking changes made in a coordinated way.
    3. The new API is part of a simplification or refactoring effort.
  • Steering: name this principle when a diff introduces a compatibility shim “for now”.

Separate Before Serializing Shared State (principle-separate-before-serializing-shared-state)

Source: skills/principle-separate-before-serializing-shared-state/SKILL.md

  • Rule: when concurrent actors might write to the same file, branch, key, or object, first ask whether they genuinely need one shared object or are merely publishing independent facts.
  • Default: give each actor its own file, key, branch, or state directory, and merge only at the place where the state is read. The leaf adds that 2 workers each writing their own field into a single state.json are still sharing mutable state.
  • Serialization: only when a single shared write target is a real invariant should access be serialized, and then structurally, with a lockfile, a single writer, sequential phases, or compare-and-swap.
  • Cautions: instructions do not provide concurrency control, and the conclusion “we need a lock” is a smell to examine before acting on it.
  • Steering: the guide’s example applies when 2 parallel attempts are about to write to the same branch: separate before serializing shared state. give each attempt its own worktree, no locks.

Guard the Context Window (principle-guard-the-context-window)

Source: skills/principle-guard-the-context-window/SKILL.md

  • Rationale: the leaf gives its reason directly. Overflowing the context degrades reasoning quality, introduces compression artifacts, and halts progress.
  • Rule: when large outputs, long files, repeated reads, or fan-out planning start to fill the context, route the bulk work to subagents. The main thread keeps summaries; raw payloads stay out of it.
  • Pattern: size each phase and cap its scope. That means limiting the number of files per phase, setting turn budgets, and counting the cost of the mechanism itself.
  • Category: poteto-mode files this principle and Never Block on the Human under “Delegation”, which the guide describes as keeping parallel work manageable.
  • Steering: a decline in answer quality late in a long session is a reason to name this principle.

Never Block on the Human (principle-never-block-on-the-human)

Source: skills/principle-never-block-on-the-human/SKILL.md

  • Premise: the leaf assumes a human who reviews work asynchronously, so the agent should never sit idle waiting for an answer. Because code changes can be reviewed and undone, an occasional wrong decision is usually cheaper than a stall.

  • Rule: make reasonable decisions, proceed, and let the human correct course afterwards.

    • The leaf’s motto is “Proceed, then present”: do the work, show the result, and explain the reasoning instead of asking “should I do X?” beforehand.
    • Let the system repair itself: record a problem when you see it, and correct it during the following round.
  • The boundary:

    Kind of actionExamples from the leafTreatment
    ReversibleWriting code, editing notes, splitting tasksProceed without blocking
    IrreversibleForce-pushing, deleting production data, sending external messagesStill requires confirmation
  • Direction and execution: the human sets the direction of the product, and carrying out the work should not stall while waiting for them.

  • Related rule: poteto-mode’s own “Autonomy” section draws a similar line, listing deploys, data deletion, customer messages, and force-pushes to shared branches as actions that always pause (see Using /poteto-mode).

  • Steering: when the agent stops to ask about a small, reversible choice, name this principle and tell it to proceed.

Outcome-Oriented Execution (principle-outcome-oriented-execution)

Source: skills/principle-outcome-oriented-execution/SKILL.md

  • Rule: optimize for the intended, verifiable end state, and give less weight to keeping every intermediate state smooth.
  • Rationale: keeping each step fully stable tends to create temporary compatibility code, which then becomes long-lived debt. The leaf prefers converging on the target architecture and proving correctness at explicit verification boundaries.
  • Core rule: end-state integrity takes priority over transitional stability. Breakage in the middle is acceptable when it is planned, scoped, and reversible.
  • Guardrails:
    • Use the principle only for planned rewrites and migrations that have explicit phase boundaries.
    • State in advance which areas may break temporarily.
    • While migrating, keep high-signal checks on the areas being actively changed.
    • Require full static and runtime verification when the plan is complete.
  • Steering: name this principle when throwaway compatibility code accumulates in a migration. Its guardrails also mean it cannot justify unplanned breakage.

Experience First (principle-experience-first)

Source: skills/principle-experience-first/SKILL.md

  • Rule: if what is easiest to implement differs from what would delight the user, the leaf sides with the user. The principle applies to trade-offs in product, UX, and feature scope.
  • Practices:
    • Each feature, control, and option needs a reason to exist.
    • “Ship less, ship better.” By the leaf’s own measure, 3 polished features outperform 10 rough ones.
    • Try ideas in disposable HTML before building them for production, where the same design decision costs far more.
    • Polish the details, such as transitions, alignment, spacing, feedback, and error states.
    • Keep the core loop tight, so that each feature either supports the central workflow or does not interfere with it.
  • Who the user is: the leaf defines the user as anyone who consumes the work. That includes the end user of a UI, the colleague who imports a library or internal API, and the engineer who will maintain the code next. Each of them deserves the same consideration, and impact should be explained from their perspective.
  • Relation to Foundational Thinking: the leaf places foundations in service of the experience. Foundational Thinking (see Premises and Thinking) decides the order in which work happens, whereas Experience First decides what the work is aiming at.
  • Steering: when the agent proposes cutting scope because the implementation would be easier, name this principle and ask it to decide from the user’s side.

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.

Running Work While You Sleep

Whether an unattended run succeeds is decided during the day, by the preparation you do before you leave. An agent can be left alone with a hard task only if it can verify its own work. The guide names three things that make this safe: a finish condition the agent can check, an isolated worktree or cloud agent, and a decision log that you audit in the morning.

This chapter follows the order in which you meet those concerns: preparing the run, writing the handoff, choosing a playbook for the shape of the work, reading the results in the morning, and the safety rules that hold throughout. The source is the guide’s overnight page together with the playbooks it routes to.

Earn trust before you start the loop

A loop you do not trust simply produces unchecked work faster, and each iteration builds on the previous mess. Before leaving a run unattended, confirm four conditions.

  • You have done the task once by hand, or watched an agent do it, so you know what a good result looks like.
  • The agent has the same tools and signals you would use: the project’s verification skill, the profiler, the logs.
  • Every stage proves its work and can stop the line when the work falls short.
  • You have read a few transcripts and converted the recurring failures into tools, skills, or checks.

Until all four hold, run the loop while you watch it. Make it autonomous only afterwards.

The overnight contract

A good handoff states the goal, the finish condition, the permissions, and an escape hatch. It does not need to be long. The guide’s example reads:

/poteto-mode im going to bed. migrate every caller to the new parser in a fresh worktree off <base>.
done means zero old callers, all parser fixtures pass, old api deleted.
keep a decision log. don't ask me before committing.
/loop until done. if you're truly stuck after a few hours, stop and write up why.

Each line does a specific job.

LineWhat it buys you
“im going to bed”A session override: the agent stops asking questions and keeps going.
“done means …”Turns the goal into checks that every iteration can run.
“fresh worktree off <base>”Keeps the run from colliding with anything else you have open.
“don’t ask me before committing”Answers in advance the permission question on which the agent would otherwise block.
/loopCursor’s built-in wake mechanism (not a pstack skill), used to re-check the finish condition.
The escape hatchLets the agent stop at a genuine dead end and explain why, instead of spending 8 hours reinterpreting the goal.

Because you will review this work after stepping away, /poteto-mode routes it through figure-it-out, which designs the phases of the run before any code is written and wires in the decision log.

A duration is not a finish condition. If you ask for “Work on this for 4 hours”, the agent has no test to apply, so the morning brings 4 hours of activity and no result. What /loop needs is a predicate that either passes or fails.

What the loop does each iteration

The Autonomous run playbook defines the cycle:

  1. Check the finish condition.
  2. Make the smallest change that the evidence justifies.
  3. Verify it against the real artifact.
  4. Commit it if it advanced the predicate, or discard it if it did not.
  5. Log one decision row.

Changes that did not help are discarded, including defensive additions that “might help”. A plateau is a reason to change approach, not a reason to stop, and the predicate is never quietly relaxed so that the run can declare victory. Only a genuine dead end, an irreversible action, or a product or preference question that no experiment can settle goes back to you.

For waking up, the playbook distinguishes two cases. When there is an event to wait for (a CI run, a merge, a ref advancing), a watcher subagent wakes the run on that event, with a long time-based heartbeat as a fallback. When there is no event, a fixed-interval heartbeat is sized to how often the result is worth re-checking.

Pausing and resuming on purpose

To stop a run deliberately, tell the agent to pause, or say that you are about to go offline or restart Cursor. The Pause safely playbook then:

  • finishes or backs out of the current atomic step and cancels nested subagents;
  • takes no irreversible action (no new PR or push);
  • commits uncommitted edits as one wip: commit on the current branch;
  • writes a resume note with the intent, progress, current state, next steps, key files, and gotchas.

Pausing happens only on an explicit request. “Keep going”, “going to bed, keep going”, and “don’t stop” never trigger it.

A fresh chat continues the work through the Session pickup playbook. It treats the previous trail as authoritative input, reconstructs the branch, the commits, and the open decisions, and names the resume point without redoing finished work. It still checks the inherited claims against the original goal on the real artifact, because a passing self-report from the previous agent does not count as proof.

When the night holds a queue or a program

The contract above drives one task to one finish condition. Some nights hold more than that.

Shape of the workUse
One taskThe Autonomous run playbook, as above.
A queue of independent PRs, merged by morningThe Autopilot-full playbook.
A queue of PRs that you will land yourselfThe Autopilot-stack playbook.
A PR that only needs to be carried to greenThe Babysit playbook.
A whole program, such as a migration across many packagesNo dedicated playbook; /poteto-mode routes it to figure-it-out.

Autopilot-full assigns a single owner agent to every PR and makes it responsible from build to merge, yet an owner never merges on the strength of its own verdict. Once the head is code-ready, a swarm of fresh verifiers examines it. After that, a rebase or a minor fix is checked by one verifier, and the full swarm returns only for new behavior or a large new diff. The prompt in the guide is brief:

/poteto-mode full autopilot on this queue. each item is independent. i want them merged by morning.

Autopilot-stack is the same playbook without the merge. You wake up to verified PRs, each with its verdict, and review them before anything lands:

/poteto-mode autopilot these five changes, but don't merge. i'll land them in the morning.

Babysit declares a mode first (drive, threads-only, or check), then clears conflicts, review threads, and CI in that order, using the watch-pr script to follow the PR’s state on GitHub. It never rebases or force-pushes, and babysitting never counts as permission to merge.

Running several projects in parallel

A Cursor Project gives one coordinator agent a persistent thread. The coordinator does not write code; it directs subagents, which run in the cloud by default, so the work continues while your laptop is closed. Each agent it starts first reads worker.md, a short rule sheet that tells workers to hold to the kickoff’s bar, make reversible decisions instead of asking, and open PRs ready for review.

The guide recommends a few habits for this setup:

  • Give each body of work (a feature, a migration, a performance push, a cleanup) its own Project.
  • Drag related chats into the Project, including finished ones, so that every agent in it has them as context.
  • Run a verification swarm on every PR before it is merged, and hand the queue to Autopilot-stack or Autopilot-full.
  • Ask the coordinator for a plan backed by data, and have it settle open questions with prototypes before it asks you.

Letting loops start themselves

Each loop described so far still depends on you to launch it. An automation triggered by a schedule or an event takes over that step. Software maintenance suits this well because it breaks into stages: triage a report, reproduce it, fix it, and verify the fix. Two rules make such a pipeline trustworthy. First, any stage is allowed to halt the line; triage may conclude that the behavior is expected, and reproduction may fail. Second, each stage hands over evidence, for example screenshots of the broken state and proof of the fix taken before and after.

For issue reports posted in a Slack channel, pstack includes a dormant automation pack of this kind, benny. It consists of 2 automations: the first triages every incoming report, and the second reproduces the bugs that triage confirms and is allowed to prepare a small draft fix. Setting it up means directing an agent to the pack’s FOR_AGENTS.md and telling it which repository to target.

The morning audit

In the morning your task is to audit decisions, not to re-read the whole night. show-me-your-work is what makes this possible. It keeps a decision log: a TSV file with one row per decision and the columns ts, phase, decision, why, evidence, and result. The file lives at decisions.tsv, or at .audit/<task-slug>.tsv when several runs share a directory. It stays out of git by default and is committed only when a reviewer needs the trail to trust the result. The log is append-only, so a wrong call is corrected by a new row, never by editing an old one.

  1. Ask for the run in review form, for example /show-me-your-work catch me up on what you did last night.
  2. Read the Attention section at the end of the reply first. Before handing back, the skill has a reviewer on another vendor’s model read the trail and the transcript and flag weak evidence, skipped verification, and risky choices.
  3. Follow only the log rows those flags point at, and open their evidence (commits, screenshots, command output).

For a quick status instead of a full audit, run ketchup in the chat that ran the work. It changes nothing, explains in plain words what has changed since your last message, and lists every call waiting on you with its recommended choice, evidence, and risk.

Treat a row whose result is INCONCLUSIVE as undecided. figure-it-out states that “Inconclusive is not a pass”, and benchmark-checklist uses the same verdict for a performance number whose limiting factor cannot be named, whose comparison ran untuned, or whose error and work counts were not checked. In that case the fix is to close the named gap and measure again, not to round the result up to success.

After a queue run, each PR comes back with its state and verdict. With Autopilot-stack the verified PRs are waiting for your review. What justifies a merge is the verifiers’ clean verdict on the patch that lands; Autopilot-full states that green CI alone never authorizes a merge.

Safety rules

The autonomy of poteto-mode has clear limits, defined in its SKILL.md and in the playbooks above.

  • Reversible work and external actions such as team chat, ticket updates, or starting evals proceed without asking.
  • Irreversible writes always pause the run: force-pushes to shared branches, deploys, data deletion, and messages to customers.
  • The finish condition is never relaxed to claim success. A plateau means a change of approach; only a genuine dead end is reported.
  • Changes that did not help are discarded, and so are speculative additions kept “just in case”.
  • In Autopilot-full, any change that loosens a gate (a raised budget, a new allowlist entry) needs a verifier’s proof and a fresh countersign from the root agent, because the owner is the party that wants the check to pass. Disabling a check, or letting it fail softly, is never kept, because such a check stops guarding every case.
  • Parallel agents work in separate worktrees or as cloud agents. Agents sharing one worktree overwrite each other, and afterwards it is impossible to tell which agent changed what.

Recipes and Tips

This chapter collects prompts that you can copy and adapt. Replace the paths and finish conditions with your own. The prompts are deliberately informal, because that is how people type them in practice, and the skills interpret intent well enough. Most prompts come from the guide’s recipes page; each is followed by a short note on why it works and, where one applies, the principle it relies on.

Fixing bugs

/poteto-mode repro the duplicate write first. if there's a cheap test path, /tdd it. then fix and rerun.

Because reproduction happens first, the fix targets a failure that has been confirmed rather than one that is assumed. The condition “if there’s a cheap test path” is deliberate: a test pushed through fragile mocks proves less than running the real command, and the playbook may say exactly that. The relevant principle is Fix Root Causes, which means following every symptom back to the earliest point where the system went wrong.

/poteto-mode read this thread. restate the underlying issue in your own words, in plain english. don't change any code yet.

For a long or noisy report, a restatement exposes any misreading at the cost of one message. Keep your own theory of the cause to yourself until the agent has stated its own. If you want only the restatement, without a playbook, use in-your-own-words.

/poteto-mode repro this with /verify-<app>. if it repros on main, fix it and show me a video as proof.

In this prompt, /verify-<app> is a placeholder for the verification skill that create-verification-skill generated for your project. Thanks to the condition “if it repros on main”, the run can end early if the bug no longer exists, and the video allows you to confirm the fix before reading the diff.

Building features

/poteto-mode prototype a few options for the settings layout. put them behind a switcher and send me screenshots of each.

You choose among things that run, instead of among descriptions. The agent answers its own questions about layout and timing along the way. The principle is Exhaust the Design Space (build 2 or 3 competing prototypes before committing).

/poteto-mode turn this design into a plan. small verifiable PRs, each with its own proof.

Ask for a plan only once the design has settled. The plan itself is the deliverable, and it names the playbook that will execute it. The principle is Sequence Work into Verifiable Units.

ask /arena for a second opinion on this thread and our approach

arena treats your current design as one candidate among several. Its synthesis tells you whether the panel found something better or confirmed what you had, which costs little compared with a design that is expensive to reverse.

Investigating

use /how first to understand how this initialization works. then use /why to figure out why it broke recently.

Mechanics first, history second. Each skill’s report names the sources it searched, so you know what the answer is based on. The choosing chapter explains how the two skills differ.

/interrogate the whole branch, but skeptically. don't change anything yet. no nitpicks unless it's an actual bug or regression in behavior.

This is a read-only adversarial review through interrogate. The qualifiers carry weight: “don’t change anything yet” keeps the run read-only, and the rule about nitpicks filters out noise in advance. What remains are findings that a rerun has proven.

Refactoring and repository hygiene

/correct agents keep adding new config flags without registering them in the schema

Instead of fixing the same mistake again by hand, correct puts the fix into the repository as architecture, a type, a lint, or a test, so the next agent cannot repeat it. The principle is Encode Lessons in Structure.

/swarm check every package under packages/ against its check.sh. one worker per package. one report.

Independent slices are checked in parallel by swarm. Each worker owns one package, and the parent waits for every slice before returning a single PASS, ISSUES, or BLOCKED report instead of raw worker output.

Opening a PR and handling review

/poteto-mode open a PR for this change. put the real-artifact evidence in the description.

This routes to the Opening a PR playbook, which works from a git worktree off trunk and writes a short body whose last heading is ## Verification. Asking for real evidence keeps that section about the actual flow or output, not about a green build. The principle is Prove It Works.

/interrogate the review comments on this branch. keep only what a rerun proves, and list what you dropped and why.

Bots and humans both file real catches and noise in the same list. Accepting or rejecting all of them is wrong either way. interrogate keeps the findings a rerun proves and reports the dropped ones with reasons, so you can still override its judgment in either direction.

Verifying claims

/create-formal-verification-skill the retry queue. a message must never be delivered twice.

The result is a single property checked across every case inside a declared scope, a counterexample expressed in the terms of your code if the code violates the property already, and a project skill that later agents run whenever that code changes. See create-formal-verification-skill.

/benchmark-checklist vet this 40% speedup before it goes in the pr description

The number is vetted before anyone else sees it. benchmark-checklist returns one of four verdicts (faster, slower, no measurable difference, or inconclusive) with the run count, the range, and the factor that limits the number. The principle is Explain the Number.

Running unattended and resuming

im going to bed, keep going autonomously until every fixture passes. do not stop. keep a decision log i can audit in the morning.

This short form works once the task and the finish condition are already in the conversation. The full handoff contract is in the overnight chapter.

/poteto-mode pause here. i'm about to go offline.

The Pause safely playbook stops at a safe boundary, records a wip: commit, and writes a resume note. Use it whenever you expect an interruption.

pick up where the previous session left off. read its resume note and decision log, then tell me the resume point.

In a new chat, the Session pickup playbook reads the previous trail as authoritative input and does not redo finished work. It still verifies the inherited claims against the goal on the real artifact. The principles are Guard the Context Window (a long transcript is parsed in a subagent) and Prove It Works.

Catching up and reading replies

/ketchup

ketchup summarizes in plain language what has happened since your previous message, and then lists every decision that is waiting for you, each with a recommended option, its evidence, and its risk. Reporting does not modify anything. If you would rather watch the update, run /ketchup-video.

/bro

That is the whole prompt. bro restates the last message more simply and briefly, without jargon. Use it when a reply is thorough but you still cannot tell what it said.

/poteto-help how do i get poteto-mode to stay on every turn?

poteto-help responds to questions about pstack by giving an explanation, a ready-to-send prompt, and a link to the relevant source. No work starts until you actually send the prompt.

Improving the setup itself

These prompts come from the guide’s make-it-yours page.

/automate-me

automate-me mines your recent transcripts for repeated preferences, asks which patterns are really yours, and drafts a personal <your-name>-mode skill that it opens as a PR. Run it again later with “update my mode skill with everything since its last edit”.

/reflect that took way too long. capture what we learned so the next run doesn't repeat it.

reflect keeps only lessons that would change a future agent’s work and waits for your approval before editing any skill. Approve a proposal only if it would change a future decision; one unusual session is an anecdote.

/poteto-mode update the review skill so it flags missing migrations, and eval the change.

Asking for the evaluation in the same prompt keeps the edit honest, because a fix written from one bad session tends to overfit that session. The Eval playbook runs the variants blind so that the candidate agents do not know they are being evaluated.

Tips

  • Do not list skills in the prompt. “use /architect then /arena then /interrogate” overrides an order that the playbook already defines. State the goal and the constraints, and name a skill only to override a default.
  • Write finish conditions that can pass or fail. “Make it better” or “work on it for an hour” gives /loop nothing to check.
  • If a prompt feels thin before you send it, run sharpen on it, for example /sharpen write the onboarding doc for the new billing service. It does not perform the task; it returns your prompt rewritten to ask for what an expert would do.
  • When a run drifts, correct it with a single line that names a principle, such as “i said the goal is to repro. i did not ask for a fix yet.” or “apply prove it works. show me the real output, not the build log.” The names of the principles serve as the shared vocabulary for such corrections.
  • To clean up prose in one step, a line such as /unslop that, no emdashes is enough.

Common Mistakes and How to Avoid Them

Every pstack user makes these mistakes at least once. Each section describes the symptom you notice, the cause behind it, and the remedy, together with the skills and principles that apply. The shorter list at the end follows the guide’s own pitfalls list.

Accepting a completion report without evidence

Symptom: the reply says “fixed, and the build passes”, yet the real flow is still broken.

Cause: a successful build proves only that the code compiles. Agents, like people, mistake proxies (a build, a type check, part of the test suite) for the behavior itself.

Remedy: make the evidence part of the definition of done. Ask for the real command output, a video of the flow, the stored value, or before-and-after numbers, and expect to see them in the reply. This is the Prove It Works principle, whose skill file explicitly rejects file timestamps, self-reports, cached output, and “it compiles” as proof. Drive the real path through the project’s verification skill, and when a report cites evidence, open it to confirm that it exists and shows what is claimed.

Letting the author grade its own work

Symptom: every item in an unattended run or a PR queue comes back as a success, but the quality varies.

Cause: the agent that wrote a change has an interest in seeing it pass. When the party that wants a green result also controls the gate, the gate weakens.

Remedy: give verification to agents that did not write the code.

  • In Autopilot-full, no owner merges on its own verdict; a swarm of verifiers checks the code before it lands.
  • Any change that loosens a gate, such as a raised budget or a new allowlist entry, needs a verifier’s proof and a fresh countersign from the root agent.
  • For a second opinion on a design, use arena or interrogate, which draw on models from different vendors. poteto-mode defines a second opinion as the same prompt on another vendor’s model.
  • show-me-your-work states that self-review is no substitute and has a reviewer on another vendor’s model read the trail before the run hands back.

Polishing an abstract plan

Symptom: a plan with no code behind it goes through round after round of adversarial review, and only the list of hypothetical risks grows.

Cause: reviewing a plan without a working artifact invents risks that will never occur. There is nothing to run, so the discussion cannot be settled.

Remedy: settle the open questions with prototypes first, through the Prototype playbook and the Exhaust the Design Space principle. Choose among things that run, then turn the chosen design into a plan. Review what got built with interrogate, which keeps only findings that a run proves.

Taking the first design

Symptom: the first shape the model proposed becomes the shape of the feature, and later work keeps fighting it.

Cause: one attempt locks in whatever the model thought of first.

Remedy: ask for prototypes, or run architect, and pick from evidence. arena exists for the case where “one attempt at a non-trivial artifact would lock in the wrong shape”, in the words of its description.

Comments and diffs that keep growing

Symptom: the PR fills with explanatory comments and incidental changes, and reviewers can no longer follow the main change.

Cause: agents tend to narrate their work in comments and to justify workarounds in prose, and small unrelated edits slip into the same diff.

Remedy: run no-comments before committing. It spawns Comment Sicko, a subagent that deletes every comment outside a short list of exceptions (license headers, constraints imposed by something external, public API docs) and marks code whose behavior needs a comment to be understood as MUST KILL, a target for renaming, extraction, or redesign. The Opening a PR playbook also runs /deslop, a skill from the separate cursor-team-kit plugin, over the diff before commit. Against diff growth, apply the Laziness Protocol: make the smallest change that solves the problem, and move incidental edits into their own PR.

Never subtracting

Symptom: features and abstractions accumulate, while old code paths and dead code stay in place.

Cause: adding produces visible progress; removing does not. Agents also copy the nearest example, so every outdated pattern left in the repository gets reproduced.

Remedy: remove before you build, following Subtract Before You Add. When you introduce a new internal API, migrate the callers and delete the old API in the same wave, following Migrate Callers Then Delete Legacy APIs. For mistakes that recur, correct treats deleting “old ways and dead code an agent would copy” as part of its first and strongest level of fix.

Wasting the context window

Symptom: decisions get worse late in a long run, and large outputs or repeated file reads fill the main thread.

Cause: the main thread holds bulky work logs, search results, and raw output from parallel workers.

Remedy: apply Guard the Context Window: route bulk work to subagents and keep only summaries in the main thread. poteto-mode tells agents to pass file pointers to subagents instead of inlined content. The Session pickup playbook parses a long transcript in a subagent and keeps only the reduced timeline. For unattended work, the decision log from show-me-your-work records each decision with an evidence pointer, never a paragraph.

Making the human the bottleneck

Symptom: the agent stops for every small confirmation, and questions pile up on your phone during a run that was meant to be unattended.

Cause: the agent asks for approval even on reversible decisions, or the handoff did not state the finish condition and permissions, which leaves the agent no option except to ask.

Remedy: apply Never Block on the Human: on reversible work, the agent proceeds, presents the result, and lets you correct course afterwards. Put the finish condition and permissions (such as “don’t ask me before committing”) into the handoff. Questions an experiment can settle should be answered by prototypes, leaving you only the product and preference decisions. The opposite also holds: irreversible actions (force-pushes to shared branches, deploys, data deletion, messages to customers) must always stop the run.

Running parallel agents in one worktree

Symptom: after a parallel run, edits have been overwritten and you cannot tell which agent changed what.

Cause: several agents wrote to the same working tree.

Remedy: run them as cloud agents, or ask for “own worktree per attempt”. The principle Separate Before Serializing Shared State says to remove the sharing first, and arena gives each candidate its own worktree or output directory for the same reason.

Looping before you trust the loop

Symptom: an overnight run produced a great deal of work, and much of it is wrong.

Cause: a loop that cannot verify its own work only produces unchecked work faster.

Remedy: get the verification skill working first, and run the loop while you watch until the conditions in the overnight chapter hold.

Editing a skill in the middle of a task

Symptom: a feature PR also contains changes to a skill that misbehaved during the work.

Cause: fixing the skill on the spot feels efficient.

Remedy: fix the skill in its own PR and keep the task moving. The make-it-yours guide warns that a skill edit tangled into feature work is invisible to review and impossible to evaluate. Write new skills through the Authoring or modifying a skill playbook instead of freehand, so validation and review take place, and test the change with the Eval playbook.

Other frequent mistakes

MistakeWhat to do instead
Listing skills in the promptIt overrides the order the playbook already defines. State the goal and constraints; name a skill only to override a default.
Leading with your theory of the causeThe agent searches where you pointed. Ask it to restate the problem first, then share your hunch.
A vague finish conditionWith “Make it better”, /loop has no test to run. Supply a command or an artifact whose result is pass or fail.
A duration as the finish condition“Work on this for 4 hours” produces activity, not a result. Give a predicate.
Trusting an unvetted numberA speedup can be an illusion caused by a warm cache or a code path that was skipped. Before you share the number anywhere, run /benchmark-checklist.
Correcting the same mistake by handA correction in chat helps one run. /correct fixes the repository so no later run repeats it.
Using arena for coveragearena repeats one brief, picks a base, and grafts the best parts. To cover slices in parallel, use swarm.
Accepting every review commentReal catches and noise arrive in one list. /interrogate keeps what a rerun proves and lists what it dropped and why.
Treating auto as a model slugNeither auto nor inherit-parent names a model. Both tell pstack to leave out the model field, so that the subagent runs on the same model as the parent chat. The model roles are covered in the setup chapter.
Reporting success from a green buildA build proves the code compiles. Ask for the real command, flow, stored value, or profile.

Your First Week and a Glossary

The guide gives two pieces of advice about adoption. One is to “start smaller than you think”: prompt plainly, watch where agents fail, and add a skill or a check only when the same failure appears twice. The other is to earn trust before running a loop, because a loop you do not trust only produces unchecked work faster.

The week below is this book’s suggested order for building that trust. It is not a schedule from pstack itself, but every step uses a skill or playbook that pstack ships, and the sequence follows the guide: one supervised task first, a verification skill early, autonomous runs last.

Day 1: run one task with /poteto-mode

Run /setup-pstack, start a new chat, and turn /poteto-mode into a Custom Mode (Option+Enter or Alt+Enter from the / menu). Then run one real, small task while you watch. Give only the goal and the done check, and observe 2 things: the playbook’s steps appearing in the todo list, and the principle names in the replies. When it finishes, confirm for yourself that the evidence it shows is real. See Installation and setup and Using /poteto-mode.

Day 2: restate first, then investigate

Practice the restatement habit: ask /poteto-mode to restate a noisy report in its own words before it changes any code. Then pick a past bug and use the two investigation skills the guide pairs in its first recipe: /how for the mechanism, then /why for the history recorded in commits and PR discussions.

Try two small helpers on the same day. /bro restates the last message in plain language without jargon, and /sharpen deepens a prompt before you send it.

Day 3: create a verification skill

Run /create-verification-skill to generate verify-<app>, a project-local skill that launches your app, checks that the instance is healthy (its “doctor” step), drives features the way a user would, captures evidence, and cleans up. It also seeds a feature map with one file per user-facing feature. The generator runs the skill once end to end before handing it over; run it once more yourself and check that the evidence survives cleanup. The guide singles this skill out as the one that pays off the most, so the rest of the week depends on it. See Verification skills.

Day 4: daily work through playbooks

Route ordinary work (a bug fix, a feature, a PR) through /poteto-mode and let it pick the playbook. Ask /interrogate to review a diff: other models try to break it, and only findings that a run proves survive.

If you notice yourself correcting the same mistake again, run /correct. It groups repeated mistakes into classes and fixes each one at the strongest level that works: architecture first, then types, lint, or CI, then tests, and written rules last. Let /no-comments run before review; it spawns Comment Sicko and applies the accepted findings.

Day 5: parallel work and PR follow-through

Use /swarm for independent checks, for example one worker per package, and confirm that you receive one aggregated report. For an open PR, ask about its status and let the Babysit playbook drive it to merge-ready through conflicts, review threads, and CI. Give each parallel agent its own worktree or a cloud subagent, so that no 2 agents share a working tree.

Day 6: a short autonomous run

While you can still watch, start a short run under the Autonomous run playbook. State the exit condition as a checkable predicate, since the guide warns that a duration such as “work on this for 4 hours” gives the agent nothing to check. Confirm that /show-me-your-work writes one row per decision.

Then tell it to pause. Check that Pause safely leaves a wip: commit and a resume note, and that a fresh chat continues from that note through Session pickup.

Day 7: a queue overnight

Before leaving a loop alone, check the guide’s 4 conditions: you have done the task once or watched an agent do it, the agent has the tools you would use, every stage proves its work and can stop the line, and you have turned repeated failures from a few transcripts into tools, skills, or checks.

For a queue of independent changes, start with Autopilot-stack, which builds and verifies PRs but leaves the merging to you. In the morning, ask /show-me-your-work to catch you up and read its Attention section first, or run /ketchup for a quicker status. Move to Autopilot-full, which also merges, once you have reviewed a few Autopilot-stack mornings and trust the verdicts. Irreversible actions still require a pause in every mode. See Running work while you sleep.

Glossary

TermMeaning
slopThe README’s word for low-value AI output: code and prose that look plausible but add little. pstack’s answer is less, but higher-quality, code.
/unslop, /deslop/unslop (a pstack skill) cuts AI tells from writing. /deslop comes from the cursor-team-kit plugin and runs before a commit.
skillA folder with a SKILL.md that tells an agent how to do one kind of task. pstack ships 58, 24 of them principles.
/poteto-modeThe entry-point skill. It matches the task to a playbook, copies its steps into the todo list, and calls other skills as the steps need them.
playbookOne of 22 ordered procedures under skills/poteto-mode/playbooks/, each for one type of work. Playbooks are not slash commands.
principleA skill named principle-* that states one rule, such as Prove It Works or Laziness Protocol. /poteto-mode names the principles behind its decisions, and you can name them to steer.
leafThe full SKILL.md of a principle, as opposed to its one-line entry in the index inside /poteto-mode.
Custom ModeA Cursor feature that keeps a skill in context on every turn. You enter it by choosing the skill with Option+Enter or Alt+Enter.
session overrideA phrase such as “going to bed” or “run until done” that tells the agent to keep working without checking in.
roleA kind of delegated work (for example bug-fix, judgment and prose, swarm workers) that /setup-pstack maps to a model.
reasoning budgetThe large, medium, or small setting in /setup-pstack. It lowers each role’s effort level by 0, 1, or 2 steps.
panelA list role, such as interrogate reviewers, where one subagent runs per entry. The default panel mixes Fable 5.2, Opus 5.5, and Gemini 4 Neon.
poteto-agentThe subagent type for delegates in a /poteto-mode run. It reads poteto-mode in full before any work.
operatorIn worker.md, the person the whole run works for, as distinct from the agent that wrote a worker’s kickoff.
Comment SickoA read-only subagent that flags comments for deletion and marks code that needs a comment to be understood as MUST KILL. /no-comments spawns it.
verification skillA project-local verify-<app> skill made by /create-verification-skill. It launches the app, checks its health, drives features as a user would, and captures evidence, guided by a feature map.
formal verification skillA project-local skill made by /create-formal-verification-skill that checks one property in every case within a stated scope, using whichever verification tool fits.
inconclusiveA verdict that is neither a pass nor a fail. Playbooks state that inconclusive is not a pass, and /benchmark-checklist uses it when it cannot name what limits a number.
decision logThe TSV file kept by /show-me-your-work, one row per decision, with columns for timestamp, phase, decision, reason, evidence pointer, and result.
/ketchupA read-only catch-up on what changed in the chat since your last message, ending with every decision waiting on you.
/swarmRuns N parallel workers across different slices or races and returns one aggregated report.
/arenaRuns N parallel attempts at the same task, picks a base, and grafts the strongest parts of the other attempts into it.
/interrogateAsks different models to break a change or design and keeps only findings that a run proves.
wip: commitThe checkpoint commit that the Pause safely playbook makes so that unfinished work is not lost.
worktreeA separate Git working tree of the same repository. pstack uses one per task or agent so parallel work does not collide.
bennyA dormant automation pack for Slack issue reports, with one automation for triage and one for reproducing confirmed bugs and drafting small fixes. It runs only on Cursor Automations.