Build the change and clean the diff

Source

This page reprints the English original.

pstack/docs/guide/05-build-and-clean.md (cursor/plugins 12d587d).

中文页

Build the change and clean the diff

The build playbooks share one discipline. Say what you observed, let the playbook demand the evidence. This page shows what to put in the prompt for each common build task, then the cleanup habit that keeps diffs reviewable.

Prompt each build playbook with what you know

A bug prompt states the symptom and asks for a reproduction first:

/poteto-mode this command emits two records after a retry. repro first, then fix and verify.

A feature prompt states the behavior and what must not change:

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

A refactoring prompt pins behavior before structure moves:

/poteto-mode move parsing into one module, zero behavior change. record the current output first and prove it's unchanged after.

A perf prompt states the measurement, not a vibe:

/poteto-mode startup takes 1.8s on this fixture. trace it, fix the measured cause, show me before and after.

Each of these routes to its playbook (Bug fix, Feature, Refactoring, Perf issue), and the playbook supplies the steps you didn’t type: reproduce before fixing, name the data shape before implementing, pin behavior before restructuring, profile before optimizing.

For sustained improvement of one number, there’s the Hillclimb playbook. Give it the metric, a target, and a floor on attempts, and it loops one hypothesis at a time with a frozen measurement harness. It keeps wins and reverts everything else.

Write the failing test first with /tdd

When a bug has a cheap local test path, the whole prompt can be two words:

/tdd implement

In context, that’s enough. /tdd writes the smallest test that fails for the intended reason, then the fix, then reruns the test. If a test would need broad harness setup or brittle mocks, the skill says so and uses the closest executable check instead. Don’t force a test where a real command is stronger evidence.

Let the TypeScript rules load themselves

typescript-best-practices has no slash command in your workflow. It loads whenever the agent touches a .ts or .tsx file and turns the type-system principles into concrete rules: discriminated unions, unknown at boundaries, exhaustive variants, schema-derived types.

Clean before you commit

The Opening a PR playbook runs /deslop on the diff before each commit and applies /unslop to the PR description and commit bodies. /deslop ships in the cursor-team-kit plugin, not in pstack. If you don’t have it, ask for the same outcome in plain words: remove narrating comments, unsupported guards, dead compatibility paths, and unrelated edits.

For prose, /unslop takes a target and any extra rules you have:

/unslop the readme changes, no emdashes

You’ll develop your own shorthand. The skill reads intent fine from terse prompts like unslop that, tighten it.

Strip the comments with /no-comments

Comments need their own pass, and not from the agent that wrote them. An author defends its comments the way you’d defend yours. So before review, hand them to fresh eyes:

/no-comments the diff

/no-comments spawns Comment Sicko, a read-only reviewer with a short keep list: license headers, doc comments on a public API, links that explain what code can’t, behavior forced by an external dependency you can’t reshape. Everything else goes. A surprise in your own code gets no such pass. The comment comes back as a refactor flag, and /no-comments fixes the flags it accepts at the root cause. When a comment claims a constraint, “do not remove”, the skill offers to encode the claim as a type, test, or lint. Either way, the comment comes out.

The division of labor is worth keeping straight. /deslop cleans slop out of the code, /unslop cleans it out of prose, and /no-comments hands the comments to a reviewer who didn’t write them.

Pitfall: cleanup is not optional polish. A diff with narrating comments and defensive dead weight reads as unfinished to reviewers, and the extra code is where the next bug hides. If the diff feels padded, say deslop it before you commit, not after review calls it out.

Next: Verify and ship.