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:
- 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.
- 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. - 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, thearchitectskill fixes the shape before any code is moved. - 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. - 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. - 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. - 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. - Rebase into small, ordered commits: subtraction first, then the reshape, then any follow-up cleanup, shaped with
principle-sequence-verifiable-unitsso 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:
- 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.
- 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.
- 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. - 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
/loopcommand until the diff reaches zero. - 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:
- Snapshot and audit. The agent first notes the output of
df -h /, then runs the bundledworktree-audit.shasscripts/worktree-audit.sh [-b <pr-base-ref>] [repo-path](principle-build-the-lever). By default the script checks merge state againstorigin/HEAD; if PRs target a different branch, pass-b origin/<branch>. Worktree paths come fromgit worktree listrather than from paths typed by hand, since a typed path likemyrepo-worktrees/xwould 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. - 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 assafea worktree the user had pinned. - 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. - Pause before irreversible loss.
wip:Nmeans 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:Nmeans untracked throwaway files, which may be dropped once the agent names them. Following the Autonomy rules ofpoteto-mode, a worktree that is clean, merged, and unused proceeds without asking, whilewipand in-use worktrees pause. - 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 withrm -rfand then runsgit worktree prune. Branch refs remain, so no commits are lost. It confirms the result withdf -h /and a fresh listing. - Reclaim space elsewhere. Simulators are usually the next largest source:
xcrun simctl --set testing delete allremoves XCTestDevices clones,xcrun simctl delete unavailableremoves unavailable devices, andxcrun simctl runtime listfollowed byruntime delete <id>removes old runtimes. Further candidates include XcodeDerivedDataandiOS DeviceSupport,~/Library/Application Support/Cursor(notablystate.vscdb.backupandsnapshots/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:
- Write the skill with
create-skill, Cursor’s built-in skill for authoring SKILL.md files. - Validate it: the frontmatter has
nameanddescription, every referenced file exists, and every link to another skill resolves. - Add test cases if the skill is structural; skip them if its effect is subjective.
- 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.