Recipes and pitfalls

Source

This page reprints the English original.

pstack/docs/guide/10-recipes-and-pitfalls.md (cursor/plugins 12d587d).

中文页

Recipes and pitfalls

Prompts worth copying, then the mistakes everyone makes once. Swap in your own paths and finish conditions. The recipes are deliberately informal. That’s how they get typed in practice, and the skills read intent fine.

Understand an unfamiliar subsystem

use /how first to understand how this initialization works. then use /why to figure out why it broke recently.

Mechanics first, history second. Each skill’s report tells you which sources it searched, so you know what the answer is grounded in.

Get a second opinion on a design

ask /arena for a second opinion on this thread and our approach

Your current design becomes one candidate among several, and the synthesis tells you whether the panel found something better or confirmed what you had. Cheap insurance before a costly commitment.

Check independent slices in parallel

/swarm check every package under packages/ against its check.sh. one worker per package. one report.

Each worker owns one package. The parent waits for every slice and returns one PASS, ISSUES, or BLOCKED report instead of raw worker dumps.

Review a branch skeptically

/interrogate the whole branch, but skeptically. don't change anything yet. no nitpicks unless it's an actual bug or regression in behavior.

The qualifiers do real work. “don’t change anything yet” keeps it read-only, and the nitpick rule pre-filters the noise so Act on findings are worth your time.

Fix a bug through a failing test

/poteto-mode repro the duplicate write first. if there's a cheap test path, /tdd it. then fix and rerun.

“if there’s a cheap test path” matters. Forcing a test through brittle mocks proves less than running the real command, and the playbook is allowed to say so.

Keep a run honest while you’re away

im going to bed, keep going autonomously until every fixture passes. do not stop. keep a decision log i can audit in the morning.

The full contract is on the overnight page. The short form works once the task and finish condition are already in the conversation.

Redirect a drifting run

Steering prompts are one line:

i said the goal is to repro. i did not ask for a fix yet.

apply prove it works. show me the real output, not the build log.

/unslop that, no emdashes

You rarely need more words. You need the right name, and the principles page is the vocabulary.

Get the reply in plain words

/bro

That’s the whole prompt. /bro restates the last message like one human talking to another, no jargon, shorter. Use it when a reply is technically thorough and you still don’t know what it said.

The pitfalls

• Enumerating skills in the prompt. “use /how then /architect then /arena” reorders steps the playbook already sequences. State the goal and constraints. Name a skill only to override a default.
• A vague finish condition. “make it better” gives /loop nothing to check. Give a command or artifact that can pass or fail.
• Parallel agents in one worktree. They overwrite each other and the diff becomes archaeology. Say “own worktree per attempt” and the isolation is free.
• Using /arena for coverage. /arena repeats one design or code brief, then picks a base and grafts the best parts. /swarm partitions slices or declared race arms and aggregates one report.
• Accepting every review comment. Bots and humans both file real catches and noise in one list. /interrogate sorts findings into act-on and dismissed buckets with reasons, and you can override either way.
• Treating auto as a model slug. auto and inherit-parent mean “omit the model field so the subagent inherits the parent chat model.” Setup covers the roles.
• Reporting success off a green build. A build proves it compiles. Ask for the real command, flow, stored value, or profile, and expect the evidence in the reply.
• Writing a SKILL.md freehand. Route it through the Authoring or modifying a skill playbook so validation and review happen.

That’s the guide. If you skipped ahead, go back to setup and run one real task. The habits stick from use, not from reading.

Back to the guide index.