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

Common Mistakes and How to Avoid Them

Every pstack user makes these mistakes at least once. Each section describes the symptom you notice, the cause behind it, and the remedy, together with the skills and principles that apply. The shorter list at the end follows the guide’s own pitfalls list.

Accepting a completion report without evidence

Symptom: the reply says “fixed, and the build passes”, yet the real flow is still broken.

Cause: a successful build proves only that the code compiles. Agents, like people, mistake proxies (a build, a type check, part of the test suite) for the behavior itself.

Remedy: make the evidence part of the definition of done. Ask for the real command output, a video of the flow, the stored value, or before-and-after numbers, and expect to see them in the reply. This is the Prove It Works principle, whose skill file explicitly rejects file timestamps, self-reports, cached output, and “it compiles” as proof. Drive the real path through the project’s verification skill, and when a report cites evidence, open it to confirm that it exists and shows what is claimed.

Letting the author grade its own work

Symptom: every item in an unattended run or a PR queue comes back as a success, but the quality varies.

Cause: the agent that wrote a change has an interest in seeing it pass. When the party that wants a green result also controls the gate, the gate weakens.

Remedy: give verification to agents that did not write the code.

  • In Autopilot-full, no owner merges on its own verdict; a swarm of verifiers checks the code before it lands.
  • Any change that loosens a gate, such as a raised budget or a new allowlist entry, needs a verifier’s proof and a fresh countersign from the root agent.
  • For a second opinion on a design, use arena or interrogate, which draw on models from different vendors. poteto-mode defines a second opinion as the same prompt on another vendor’s model.
  • show-me-your-work states that self-review is no substitute and has a reviewer on another vendor’s model read the trail before the run hands back.

Polishing an abstract plan

Symptom: a plan with no code behind it goes through round after round of adversarial review, and only the list of hypothetical risks grows.

Cause: reviewing a plan without a working artifact invents risks that will never occur. There is nothing to run, so the discussion cannot be settled.

Remedy: settle the open questions with prototypes first, through the Prototype playbook and the Exhaust the Design Space principle. Choose among things that run, then turn the chosen design into a plan. Review what got built with interrogate, which keeps only findings that a run proves.

Taking the first design

Symptom: the first shape the model proposed becomes the shape of the feature, and later work keeps fighting it.

Cause: one attempt locks in whatever the model thought of first.

Remedy: ask for prototypes, or run architect, and pick from evidence. arena exists for the case where “one attempt at a non-trivial artifact would lock in the wrong shape”, in the words of its description.

Comments and diffs that keep growing

Symptom: the PR fills with explanatory comments and incidental changes, and reviewers can no longer follow the main change.

Cause: agents tend to narrate their work in comments and to justify workarounds in prose, and small unrelated edits slip into the same diff.

Remedy: run no-comments before committing. It spawns Comment Sicko, a subagent that deletes every comment outside a short list of exceptions (license headers, constraints imposed by something external, public API docs) and marks code whose behavior needs a comment to be understood as MUST KILL, a target for renaming, extraction, or redesign. The Opening a PR playbook also runs /deslop, a skill from the separate cursor-team-kit plugin, over the diff before commit. Against diff growth, apply the Laziness Protocol: make the smallest change that solves the problem, and move incidental edits into their own PR.

Never subtracting

Symptom: features and abstractions accumulate, while old code paths and dead code stay in place.

Cause: adding produces visible progress; removing does not. Agents also copy the nearest example, so every outdated pattern left in the repository gets reproduced.

Remedy: remove before you build, following Subtract Before You Add. When you introduce a new internal API, migrate the callers and delete the old API in the same wave, following Migrate Callers Then Delete Legacy APIs. For mistakes that recur, correct treats deleting “old ways and dead code an agent would copy” as part of its first and strongest level of fix.

Wasting the context window

Symptom: decisions get worse late in a long run, and large outputs or repeated file reads fill the main thread.

Cause: the main thread holds bulky work logs, search results, and raw output from parallel workers.

Remedy: apply Guard the Context Window: route bulk work to subagents and keep only summaries in the main thread. poteto-mode tells agents to pass file pointers to subagents instead of inlined content. The Session pickup playbook parses a long transcript in a subagent and keeps only the reduced timeline. For unattended work, the decision log from show-me-your-work records each decision with an evidence pointer, never a paragraph.

Making the human the bottleneck

Symptom: the agent stops for every small confirmation, and questions pile up on your phone during a run that was meant to be unattended.

Cause: the agent asks for approval even on reversible decisions, or the handoff did not state the finish condition and permissions, which leaves the agent no option except to ask.

Remedy: apply Never Block on the Human: on reversible work, the agent proceeds, presents the result, and lets you correct course afterwards. Put the finish condition and permissions (such as “don’t ask me before committing”) into the handoff. Questions an experiment can settle should be answered by prototypes, leaving you only the product and preference decisions. The opposite also holds: irreversible actions (force-pushes to shared branches, deploys, data deletion, messages to customers) must always stop the run.

Running parallel agents in one worktree

Symptom: after a parallel run, edits have been overwritten and you cannot tell which agent changed what.

Cause: several agents wrote to the same working tree.

Remedy: run them as cloud agents, or ask for “own worktree per attempt”. The principle Separate Before Serializing Shared State says to remove the sharing first, and arena gives each candidate its own worktree or output directory for the same reason.

Looping before you trust the loop

Symptom: an overnight run produced a great deal of work, and much of it is wrong.

Cause: a loop that cannot verify its own work only produces unchecked work faster.

Remedy: get the verification skill working first, and run the loop while you watch until the conditions in the overnight chapter hold.

Editing a skill in the middle of a task

Symptom: a feature PR also contains changes to a skill that misbehaved during the work.

Cause: fixing the skill on the spot feels efficient.

Remedy: fix the skill in its own PR and keep the task moving. The make-it-yours guide warns that a skill edit tangled into feature work is invisible to review and impossible to evaluate. Write new skills through the Authoring or modifying a skill playbook instead of freehand, so validation and review take place, and test the change with the Eval playbook.

Other frequent mistakes

MistakeWhat to do instead
Listing skills in the promptIt overrides the order the playbook already defines. State the goal and constraints; name a skill only to override a default.
Leading with your theory of the causeThe agent searches where you pointed. Ask it to restate the problem first, then share your hunch.
A vague finish conditionWith “Make it better”, /loop has no test to run. Supply a command or an artifact whose result is pass or fail.
A duration as the finish condition“Work on this for 4 hours” produces activity, not a result. Give a predicate.
Trusting an unvetted numberA speedup can be an illusion caused by a warm cache or a code path that was skipped. Before you share the number anywhere, run /benchmark-checklist.
Correcting the same mistake by handA correction in chat helps one run. /correct fixes the repository so no later run repeats it.
Using arena for coveragearena repeats one brief, picks a base, and grafts the best parts. To cover slices in parallel, use swarm.
Accepting every review commentReal catches and noise arrive in one list. /interrogate keeps what a rerun proves and lists what it dropped and why.
Treating auto as a model slugNeither auto nor inherit-parent names a model. Both tell pstack to leave out the model field, so that the subagent runs on the same model as the parent chat. The model roles are covered in the setup chapter.
Reporting success from a green buildA build proves the code compiles. Ask for the real command, flow, stored value, or profile.