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: 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.