Recipes and pitfalls
Recipes and pitfalls
Section titled “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
Section titled “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.
Restate a noisy report before touching code
Section titled “Restate a noisy report before touching code”/poteto-mode read this thread. restate the underlying issue in your own words, in plain english. don't change any code yet.A misreading shows up in the restatement, where it costs one message to correct. Keep your own theory to yourself until the agent has stated its own. /in-your-own-words asks for the restatement alone, with no playbook.
Sharpen a prompt before you send it
Section titled “Sharpen a prompt before you send it”/sharpen write the onboarding doc for the new billing service.The agent names what an expert would do that you didn’t ask for, the raw material they’d start from, their methods and tools, and an outside check that the result is right. It hands back your prompt rewritten to ask for that and doesn’t do the task. Send the rewrite when it reads right.
Prototype before you pick
Section titled “Prototype before you pick”/poteto-mode prototype a few options for the settings layout. put them behind a switcher and send me screenshots of each.You pick from things that run, not from descriptions. The agent answers its own layout and timing questions along the way.
Turn a settled design into a plan
Section titled “Turn a settled design into a plan”/poteto-mode turn this design into a plan. small verifiable PRs, each with its own proof.Ask only after the design settles. The plan is the deliverable, and it names the playbook that will execute it.
Get a second opinion on a design
Section titled “Get a second opinion on a design”ask /arena for a second opinion on this thread and our approachYour current design becomes one candidate among several, and the synthesis tells you whether the panel found something better or confirmed what you had. It costs little next to a design that is expensive to reverse.
Check independent slices in parallel
Section titled “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
Section titled “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
Section titled “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.
Repro and fix a report with proof
Section titled “Repro and fix a report with proof”/poteto-mode repro this with /verify-<app>. if it repros on main, fix it and show me a video as proof.“if it repros on main” lets the run stop early when the bug is already gone. The video lets you check the fix before you read the diff.
Prove a property tests rarely reach
Section titled “Prove a property tests rarely reach”/create-formal-verification-skill the retry queue. a message must never be delivered twice.You get one property checked in every case within a stated scope, a counterexample in your code’s terms if the code already breaks it, and a project skill the next agent runs on any change to that code.
Vet a number before you post it
Section titled “Vet a number before you post it”/benchmark-checklist vet this 40% speedup before it goes in the pr descriptionYou get faster, slower, no measurable difference, or inconclusive, with the run count, the range, and what limits the number.
Stop correcting the same mistake
Section titled “Stop correcting the same mistake”/correct agents keep adding new config flags without registering them in the schemaThe fix lands in the repo as architecture, a type, a lint, or a test, so the next agent can’t make the mistake.
Ask how without starting the work
Section titled “Ask how without starting the work”/poteto-help how do i get poteto-mode to stay on every turn?You get an answer, a prompt to send, and a link to the source. Nothing runs until you send that prompt.
Keep a run honest while you’re away
Section titled “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
Section titled “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 emdashesYou rarely need more words. You need the right name, and the principles page is the vocabulary.
Get the reply in plain words
Section titled “Get the reply in plain words”/broThat’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.
Catch up on a chat you left running
Section titled “Catch up on a chat you left running”/ketchup/ketchup tells you in plain words what changed since your last message, then lists each call waiting on you with its pick, evidence, and risk. It changes nothing while it reports.
To watch the catch-up instead, run /ketchup-video. It shows what happened in a short silent video of slides, and lists the calls waiting on you as text under it.
The pitfalls
Section titled “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
/loopnothing to check. Give a command or artifact that can pass or fail. - Leading with your theory of the cause. The agent searches wherever you pointed. Ask it to restate the problem first, then share your hunch.
- Taking the first design. One attempt locks in the first shape the model thought of. Ask for prototypes or
/architectand pick from evidence. - Polishing an abstract plan. Adversarial review of a plan with no code behind it invents risks that will never happen. Settle the open questions with prototypes, then review what got built.
- Parallel agents in one worktree. They overwrite each other, and nobody can tell which agent changed what. Run them as cloud agents, or say “own worktree per attempt”.
- Looping before you trust the loop. A loop that can’t verify its own work only makes unchecked work faster. Get the verification skill working first.
- Trusting an unvetted number. A warm cache or a skipped code path can fake a speedup. Run
/benchmark-checklistbefore the number goes anywhere. - Correcting the same mistake by hand. A correction in chat helps one run.
/correctfixes the repo so no later run repeats it. - Using
/arenafor coverage./arenarepeats one design or code brief, then picks a base and grafts the best parts./swarmpartitions 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.
/interrogatesorts findings into act-on and dismissed buckets with reasons, and you can override either way. - Treating
autoas a model slug.autoandinherit-parentmean “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.mdfreehand. 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.
