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

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.