/pstack:how
AutoIn one lineExplains how a piece of code runs today: the flow, the key types, the easy-to-miss traps.
- When to use
- You want to understand it before changing it, or you suspect it's slow.
/pstack:how How do we dedupe notifications? Is there an N+1 query when we look up subscribers?Just asking vs. using it
The same request, typed plainly or with /pstack:how. Here's what changes.
With /pstack:howWhat the document says
5 sections, about 450 words, 2 min to read. Click a section to read it.
OpeningIt sets the depth at a senior engineer onboarding onto a subsystem, and names the models for the read-only explorer and explainer helpers.
- 1Assess complexitySizes the question. One module gets one helper that explores and explains. A multi-file subsystem gets explorers. Unsure means simple.
- 2Explore (complex only)Splits the question into 2 to 4 angles and sends one explorer per angle, all in one message.
- 3Synthesize (complex only)After every explorer returns, one explainer gets all their findings and writes a single explanation.
- 4PresentHands you the explainer's text with only light edits for clarity.
- 5Output formatFive sections: Overview, Key Concepts, How It Works, Where Things Live, Gotchas. Any that don't apply are dropped.
Wording worth borrowing
A few sentences from the original: what each one makes the AI do, why it works, and how you can borrow it.
Set a floor and a ceiling
enough to build a working mental model, not so much that it reads like annotated source code
- Makes the AI
- The explanation is enough to understand how it works, without reading the code line by line.
- Why it works
- Saying both "at least this deep" and "no deeper than this" tells the AI exactly how much detail to give.
- Borrow it
- Give both ends: "Explain enough that I can change the settings myself, but don't walk through every option."
Give a default for doubt
When in doubt, take the simple path.
- Makes the AI
- When it can't tell how big the question is, it takes the simple path with one helper instead of a big operation.
- Why it works
- Deciding ahead which way to lean when unsure stops the AI from stalling or blowing up a small task.
- Borrow it
- Give it a default: "If you're not sure whether to add a feature, don't."
State your reading, then start
If the scope is ambiguous, state your interpretation and explore.
- Makes the AI
- When the question is vague, it says how it reads it and gets going; you can redirect any time.
- Why it works
- Saying its reading out loud means it doesn't stall waiting for you, and you can see if it misread.
- Borrow it
- Add: "Where I'm unclear, write one line on how you read it, then keep going without waiting for me."
Full text
The SKILL.md the AI reads, as written.
descriptionUse for "how does X work", code walkthroughs before changing something, and placement / ownership / layering questions ("where should this live", "which package owns this", "is this the right layer"). Explains subsystem architecture, runtime flow, onboarding mental models. Use why for motivation.
How
Explore the codebase to answer "how does X work?" questions. Produce architectural explanations at the level of a senior engineer onboarding onto a subsystem, enough to build a working mental model, not so much that it reads like annotated source code.
Every spawn is a Task subagent with subagent_type: generalPurpose and readonly: true. Explorers use the how explorer line in the pstack settings file (~/.cursor/rules/pstack-models.mdc in Cursor, ~/.claude/rules/pstack-models.md in Claude Code, ~/.agents/pstack-models.md in other harnesses) (default grok-4.7-xhigh-fast), and every explainer uses the how explainer line (default claude-opus-5-5-xhigh). Set model to that line's value, or to the default if the file or the line is missing. Leave model unset when the value is auto or inherit-parent. If your subagent tool rejects a slug, use the default and say so. If it rejects the default, use the closest valid slug of the same family from its error message or your harness's model list. Pick each subagent's reasoning level and fast or standard speed for the job, per the Subagents section of the poteto-mode skill.
1. Assess complexity
If the scope is ambiguous, state your interpretation and explore. The user can redirect.
- Simple (a single module, a small utility, a narrow question such as "how does function X work"): no explorers. Spawn one explainer that explores and explains in one pass, built from
references/explainer-prompt.mdwithout the explorer-findings section. Go to step 4. - Complex (a subsystem spanning multiple files or services, a cross-cutting feature, a full architectural overview): go to step 2.
When in doubt, take the simple path.
Other harnesses. The spawns in this skill use Cursor's Task tool. In another harness, use its subagent tool: Agent in Claude Code (subagent_type: general-purpose), task in OpenCode (subagent_type: general), spawn_agent in Codex. Keep the prompt and the model. Drop parameters your tool doesn't have. If your harness has no subagent tool, as in Pi without an extension, run each role yourself, one after another.
2. Explore (complex only)
Decompose the question into 2 to 4 angles, each a distinct slice of the subsystem. Spawn all explorers in a single message, each with references/explorer-prompt.md and its angle filled in.
3. Synthesize (complex only)
Once all explorers have returned, spawn one explainer with references/explainer-prompt.md and every explorer's findings filled in.
4. Present
Present the explainer's output. Light edits for clarity or context from the conversation are fine. Do not substantially rewrite it.
Output format
The explanation uses the sections defined in references/explainer-prompt.md, dropping any that do not apply: Overview, Key Concepts, How It Works, Where Things Live, Gotchas.
Original by Lauren Tan (poteto), MIT license. Checked against the pstack mirror at 97de40d. View on GitHub