Understand the code before changing it

Editing code you don't understand is how subtle regressions ship, and that's as true for the agent as for you. Agents usually fail in one of two ways. They misread what you want, or they don't have the context to do the work right. What goes in a prompt handles the first. This page handles the second.

pstack gives you four ways in. /how explains what the code does now. /why digs up the reasons it's shaped that way. /teach blends both into one explanation. /recall rebuilds your own recent context on a topic. Each one also makes the agent explain itself in words you can check. That's how you supervise an agent that may know the code better than you do.

Start with a read-only investigation

When the cause is unclear, ask for findings, not a fix:

/poteto-mode investigate why background jobs time out every few hours. give me what we know, what data you used, and your best hypotheses. don't change any code yet.

"don't change any code yet" routes this to the Investigation playbook. It runs /how, adds /why for questions about motivation, and returns a cited explanation. For a choice between options, it returns a recommendation with a trade-offs table. Asking "what data you used" makes the agent separate its evidence from its guesses. When the findings point at a fix, start the fix as a new task.

Trace behavior with /how

/how do we dedupe notifications? is there an n+1 when we look up subscribers?

Ask the question you actually have. /how reads the code and answers at the level of a senior engineer onboarding you onto the subsystem, with the runtime flow, the key types, and the non-obvious parts. For a big subsystem it fans out two to four read-only explorers first. For a narrow question it just reads and explains.

Dig up history with /why

/why was the retry limit set to five? does the reason still hold?

/why works like a detective on a cold case. It starts from source control, then queries whatever evidence categories your MCPs expose, such as the issue tracker, long-form docs, team chat, observability, error tracking, and analytics, all in parallel. The report cites everything, separates direct evidence from inference, and says "appears to" when the record is thin. A null result gets reported too, because "nobody wrote down why" is itself an answer.

The two compose naturally. do why first then how is a perfectly good prompt when you suspect the history explains the mess.

Actually understand it with /teach

/teach me how this PR changes retries. convince me it fixes the cause and not the symptom.

/teach is for when a summary isn't enough. It runs /how and /why, for a small change maybe just one of them, and weaves the findings into a plain explanation that builds up diagram by diagram. The "convince me" framing is worth stealing. It turns the explanation into an argument you can poke at instead of a tour.

It works on the agent's own choices too:

/teach me why you implemented it this way and not with a queue. what did you trade off, and why?

Teaching helps the agent as much as you. An agent that has to explain its work must read the code and back each claim with evidence, instead of stating it confidently and moving on.

Rebuild your own context with /recall

/recall catch me up on the export work from last week

/recall mines your own recent chats plus the shared record (issues, prior fixes, errors still firing) and hands back a brief on where things stand and what's next. Your old chats hold context that a fresh agent lacks, so start new work on an old topic by loading it first, then hand over the new input:

/recall my work on the virtualized list from yesterday, then read this bug report.

If you want to resume one specific chat, that's the Session pickup playbook below, not /recall.

Take over prior work with Session pickup

When another agent (or you, last week) left a branch mid-flight:

/poteto-mode take over this branch. read the decision log, figure out what's done, and continue from there. don't redo finished work.

The Session pickup playbook treats the prior trail as authoritative. It reconstructs the branch state and decisions, names the resume point, and verifies inherited claims against the original goal instead of re-deriving everything from scratch.

Pitfall: don't skip this page's skills because "the agent will read the code anyway." An agent that starts editing without a traced model tends to fix the symptom at the first plausible spot. /how first is cheaper than the second bug.

Next: Design the change.