Skip to content

Cursor plugin specification and official plugins

TypeScript

pstack: add refactoring playbook (#81)

laurenf18ffc1bd6b4
diff --git a/pstack/skills/poteto-mode/SKILL.md b/pstack/skills/poteto-mode/SKILL.md
index 5e0861be..974a33d3 100644
--- a/pstack/skills/poteto-mode/SKILL.md
+++ b/pstack/skills/poteto-mode/SKILL.md
@@ -108,6 +108,7 @@ A large or cross-cutting effort (a migration across many call sites, an ambitiou
- **Perf issue.** A measured slowness to trace and improve against a baseline. Full steps: `playbooks/perf-issue.md`.
- **Runtime forensics.** Diagnosing a runtime symptom (leak, idle-CPU spin, glitch) from live instrumentation; the deliverable is a diagnosis, not a fix. Full steps: `playbooks/runtime-forensics.md`.
- **Feature.** New or changed behavior, built from a named data shape. Full steps: `playbooks/feature.md`.
+- **Refactoring.** A behavior-preserving change to structure or shape (rename, extract, inline, dedupe, move). Full steps: `playbooks/refactoring.md`.
- **Prototype.** A throwaway sketch to make a design decision cheaply before building it for real ("prototype", "mock it up", "try this layout"). Full steps: `playbooks/prototype.md`.
- **Visual parity.** Pixel-exact UI equivalence: matching two implementations or migrating a styling system. Full steps: `playbooks/visual-parity.md`.
- **Authoring or modifying a skill.** Writing or editing a SKILL.md. Full steps: `playbooks/authoring-a-skill.md`.
diff --git a/pstack/skills/poteto-mode/playbooks/refactoring.md b/pstack/skills/poteto-mode/playbooks/refactoring.md
new file mode 100644
index 00000000..4e3b0785
--- /dev/null
+++ b/pstack/skills/poteto-mode/playbooks/refactoring.md
@@ -0,0 +1,15 @@
+### Refactoring
+
+**You own the contract. The structure changes; the behavior does not.** For "refactor", "rename", "extract", "inline", "dedupe", "restructure", "move this module", "tidy up this area". Distinct from Feature, which adds behavior, and Bug fix, which corrects it.
+
+A refactor that smuggles in a behavior change loses its safety net. If the cleanup reveals a missing feature or a real bug, split it out and ship the structural change first against the pinned contract. A redesign is allowed, but name it and route to Feature rather than letting it walk in under the refactor banner. Large or cross-cutting structural work (a migration across many call sites, a coordinated reshape of many subsystems) belongs to the **figure-it-out** skill; this playbook is the focused-to-medium structural change.
+
+1. Pin the behavior contract first. Run the **how** skill over the affected subsystem to learn what the contract actually is, then write a characterization test, a snapshot, or an equivalence harness that captures the current behavior before any structure moves. The harness is what makes "refactor" a checkable claim (the **principle-prove-it-works** skill). If the area has no coverage, write the pin before touching structure. Type check and lint are not a pin.
+2. Name the target shape. State what the module layout, types, and call graph should be if built today (the **principle-foundational-thinking** skill, the **principle-redesign-from-first-principles** skill). If the target crosses a function boundary, run the **architect** skill for parallel design exploration of the shape before the move.
+3. Subtract before you add. Delete dead weight, collapse one-caller wrappers, drop redundant validators, and remove orphan references before introducing the new shape (the **principle-subtract-before-you-add** skill). The smallest change that reaches the target shape ships (the **principle-laziness-protocol** skill). A speculative cleanup that "might help" gets reverted, not left to ride.
+4. Move in small behavior-preserving steps, each keeping the pin green. For API reshapes, migrate every caller and delete the old API in the same wave (the **principle-migrate-callers-then-delete-legacy-apis** skill). No compatibility shims, no parallel old-and-new paths waiting for cleanup later. Spot-check every rename against the actual files; renames silently miss usages in strings, prose, and back-references. Delegate the mechanical edits to a `composer-2.5-fast` subagent with a specific scope (file paths, the names being moved, the behavior to hold); review the diff yourself.
+5. Prove behavior is unchanged on the real artifact, not "it compiles" (the **principle-prove-it-works** skill). For larger reshapes, run an equivalence check. A script that diffs old-vs-new outputs, a recorded baseline replayed against the new code, or a smoke run on the matching surface via the relevant control skill. Own the verification yourself; do not trust a delegate's "looks good" summary.
+6. Confirm the change earns its place. The success measure is reduced reader load (the **principle-minimize-reader-load** skill). Fewer layers between question and answer, less hidden state, fewer indirections without a second consumer. If the diff does not lower reader load somewhere, the refactor does not earn its place and should be reverted.
+7. Rebase into small ordered commits that tell the story. A subtraction commit, then the reshape, then any follow-on cleanup, so a single revert undoes one slice. Run **Opening a PR**.
+
+**Reply:** the structure that changed, the pin you held it against, the equivalence proof, the reader-load delta, what shipped and what got reverted. No new behavior.