Copy this first
/pstack:poteto-mode startup takes 1.8s on this fixture. trace it, fix the measured cause, show me before and after.This is the example from pstack’s own docs.
- “1.8s on this fixture”: a measured number on fixed test data. It can’t compare “feels a bit laggy.”
- “trace it”: a trace records how long each step of the program takes.
- “the measured cause”: it fixes what the trace shows, not what it guesses.
- 1Measure a baselinep50 about 900ms
- 2See where time goesTake a trace
- 3Fix the measured causeNot the guessed one
- 4Measure again, same datap50 under 200ms, same results
Not faster? Revert and go again
A member site example
A member site runs on Cloudflare Workers, with data in D1. The member list endpoint keeps getting slower.
/pstack:poteto-mode The member list endpoint /api/members has a p50 of about 900ms under local wrangler dev, with 5000 test members imported.
Measure a baseline first and tell me where the time goes. Fix the measured cause.
It's fixed when, with the same data, p50 is under 200ms and the members returned (count and content) are exactly the same as before the fix.
Alternate the two sides 7 runs each, give me the median and range, then run /pstack:benchmark-checklist.- “Exactly the same members returned”: faster but missing data means it isn’t fixed.
- “Alternate 7 runs each”: a number from one run could be luck.
- 5000 members: a scenario you can repeat. With too little data, the problem may not show up.
Where to look after you send it
At the start: the baseline number. If it says “this will be faster” without measuring, stop it.
At the end: four things. The baseline, the number after the fix, the difference, and where the data files are. If a result is inconclusive, it says so. That isn’t a pass.
A number that looks too good: /pstack:benchmark-checklist
/pstack:benchmark-checklist Check this 40% speedup before it goes into the PR descriptionThe perf playbook runs it on its own. For a number someone gave you, run it yourself. Seven questions, each backed by a real run:
- Why isn’t it twice as fast? Name the bottleneck holding it there.
- Are both sides set up like production? No debug build against a release build.
- Does it beat a physical limit? Faster than the disk means it measured something else.
- Were there errors? Rejected requests are often fast. Count them.
- Can you repeat it? Alternate the sides, at least 5 runs each. Report the median and range.
- Does it matter to users? A function that takes 1% of the time can save at most 1%.
- Did the timed work really happen? A promise nobody awaits runs very fast.
There are four verdicts: faster, slower, no measurable difference, or inconclusive.
Just tell me where it’s slow
/pstack:poteto-mode This is a cpuprofile I recorded during a slow startup. Tell me where the time goes and which lines of code are responsible. Don't fix anything yet.- You have a recorded file (cpuprofile, trace, heap snapshot): it reads only that file and finds the slowest lines.
- It’s happening right now (memory keeps growing, CPU busy while idle, the UI flickers): it records the running program. Then a small experiment confirms the cause.
Both hand back only a sourced diagnosis. Then you decide how to fix it.
Keep pushing one number down
For a number you want to keep improving, like bundle size or first-screen time, use Hillclimb. Give it a metric, a target, and a minimum number of rounds.
/pstack:poteto-mode hillclimb the side panel's first-open time. Target: at least 50% faster than baseline, and try at least 10 rounds. Log one line in the decision log per round.- “At least 10 rounds”: stops it from hitting the target by luck in round one and quitting.
- One change and one measurement per round. Faster means it’s kept and committed alone. Not faster means it’s reverted.
- One line per round. It goes in
decision.tsv, so you can see every attempt.
Stuck?
It says “this will make it faster” without measuring.
Reply: “Measure first. Give me the baseline number and the trace file path, then tell me what to change.”
The improvement is absurdly large. I don't believe it.
Run /pstack:benchmark-checklist. Look hardest at questions 3 and 7. This matches explain-the-number. It means: say what limits the number, and rule out that it measured the wrong thing. It’s the name of a pstack principle.
It ran once and drew a conclusion.
Reply: “Alternate the two sides at least 5 runs each, and report the median and range. If the gap is smaller than the run-to-run variation, there’s no difference.”
Hillclimb is stuck on one number, and it wants to stop.
It should try a different approach first. It can’t loosen the target to call it done. If it’s truly stuck, it should tell you what’s going on.