Skip to content
Full guide · step 5 of 820 minutes

Design, build, clean up

In one lineFor big changes, compare a few designs or build prototypes. Say what you saw while building. Clean up before handing it over.

You need: A change you're about to make

Most changes need no design step

When a change touches several places, /pstack:poteto-mode designs it first on its own. Name the skills below only when you want it to think one step more.

  1. 1Settle the design/pstack:architect, /pstack:arena, prototypes
  2. 2BuildSay what you see; /pstack:tdd if a test is easy
  3. 3Pick holes/pstack:interrogate keeps only problems it can run
  4. 4Clean up/pstack:unslop, /pstack:no-comments
DiagramThe dashed step is optional: for most changes /pstack:poteto-mode designs on its own; name these skills only when you're unsure.

It touches several places: /pstack:architect

Copy this
/pstack:architect Design the import flow first, don't write code yet. What I care about most is how callers use it.

What you get: a few designs side by side. Each one starts with “how a caller uses it”. It then builds the one it picked. To see the design first, add “with checkpoint, stop and show me before you implement”.

While it builds against the design, if something doesn’t fit, it stops and tells you. If the design itself is wrong, it throws it out and starts over instead of patching it. That’s normal.

One decision you’re unsure about: /pstack:arena

Use it for names, formats or algorithms that will be hard to change later.

Copy this
/pstack:arena This cache key format will be hard to change later. Give me 5 options.

What you get: several AIs each write a version. A model from another family scores them (say, Grok instead of Claude). The top one becomes the base, and good ideas from the rest get added.

It’s written, now find the flaws: /pstack:interrogate

Copy this
/pstack:interrogate Review the whole branch, and be picky. Don't report nitpicks unless it's a real bug or a regression.

What you get: only problems that a command actually made fail. It doesn’t change code. It also lists the problems it threw out. Read that list too. If it threw one out wrongly, ask it to check again.

Can’t settle it? Prototype

Copy this
/pstack:poteto-mode Build a few prototypes of the new dropdown menu. Give me screenshots or screen recordings to compare.

What you get: a few throwaway drafts, each screenshotted or timed, side by side for you to pick. This works for UI, behavior and algorithms.

Plans work the same way. Prototype the parts you’re unsure about, then write what you saw into the plan. A plan that never tried anything can be wrong, however detailed it gets.

A big feature: write the tutorial first, then the design

The author's version, swap in your own task
(1) /pstack:recall what I did on virtual list bugs and perf issues in the past 7 days. Use /pstack:how and /pstack:why to understand how our current virtual list works.
(2) Then plan with /pstack:poteto-mode and /pstack:technical-writing: design a new engine that removes flicker and jitter at the root. Start with a tutorial on how I'd use the new package to add a virtual list to a React app.
(3) Once the plan is written, /pstack:teach me, and prove the new approach beats the current one.

Each part does one job:

  • Bring back the context: the bugs you fixed and how it works now are what the new design has to solve.
  • Design from the usage: write how people will use it first, and you see right away whether it’s easy to use.
  • Ask for proof: reasons aren’t enough, ask for a comparison. With a verification skill in the project, it can show real evidence.

Step 3 said not to line up skills in your message. That’s for small tasks. For a big design like this, the author names skills part by part, each part naming only what it needs.

While building, say what you saw

  • Fix a bug: give the symptom, add “reproduce it first”. Example: “After a retry it writes two records. Reproduce it first, then fix it, then verify.”
  • Add a feature: say what must not change. Example: “Add a –json flag. The text output must not change at all.”
  • Refactor: say behavior stays the same. Example: “Record the current output first, then prove it didn’t change.”
  • Find what’s slow: give a measured number. Example: “Startup takes 1.8 seconds. Capture a trace and give me a before/after.”

For the full approach, see fix a bug, add a feature, refactor, find what’s slow.

When a local test can catch the bug, type:

Copy this
/pstack:tdd implement

What you get: a failing test first, then the fix, then a run that shows it passing.

When you change TypeScript, name /pstack:typescript-best-practices. It won’t load on its own.

Clean up before you hand it over

  • Writing: /pstack:unslop removes the AI tone. You can add rules: /pstack:unslop Clean up the new README content, no em dashes.
  • Comments: /pstack:no-comments sends an AI that didn’t write the code to review the comments. Only the needed ones stay.
  • Code: just say “Remove narrating comments, unjustified defensive checks, dead compatibility code, and changes unrelated to this task.”

Stuck?

It went with the first design and didn't give me a choice.

Say “don’t decide yet, build two or three prototypes and compare them side by side”. Or type exhaust the design space, which means “try all the options”. It’s a principle name pstack knows, so typing it as is works.

I want it to write a plan before it starts.

Once the design is settled, say: /pstack:poteto-mode Turn this design into a plan. Split it into small PRs that can each be verified on their own, each with its verification steps. It only writes the plan, and doesn’t build. A PR is a set of changes handed to someone to review.

How is /pstack:swarm different from /pstack:arena?

/pstack:arena has several AIs do the same job, and picks the best. /pstack:swarm cuts a big job into pieces for several AIs. See how /pstack:arena differs from /pstack:swarm.

Before moving on, check

An unofficial beginner's guide to pstack, not its official docs. pstack is made by poteto; the official repo is the source of truth for commands and behavior. The original guide source is on GitHub.

Hosted by airali. Adapted from Xiaoxiaodong's MIT-licensed guide.