Skip to content
  1. Skills at a glance
  2. Understand the code
  3. /pstack:how

/pstack:how

Auto

In 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.
Say it like this
/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.

Just askingWith /pstack:how
Walks through the code like annotated source.Explains in five parts: Overview, Key Concepts, How It Works, Where Things Live, Gotchas.
Edits code while it looks around.Runs every helper read-only, so your code stays untouched.
Silently guesses what an unclear question means.States its reading of the question, then explores. You can redirect anytime.

What 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.

  1. 1Assess complexitySizes the question. One module gets one helper that explores and explains. A multi-file subsystem gets explorers. Unsure means simple.
  2. 2Explore (complex only)Splits the question into 2 to 4 angles and sends one explorer per angle, all in one message.
  3. 3Synthesize (complex only)After every explorer returns, one explainer gets all their findings and writes a single explanation.
  4. 4PresentHands you the explainer's text with only light edits for clarity.
  5. 5Output formatFive sections: Overview, Key Concepts, How It Works, Where Things Live, Gotchas. Any that don't apply are dropped.

See the wording worth borrowingRead the full text

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.

  1. 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."
  2. 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."
  3. 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.md without 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

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.