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

/pstack:why

Auto

In one lineFinds out "why it was done this way" from Git history and docs, with a source for every claim.

When to use
You see odd code or config and want its story, and whether the reason still holds.
Install with
how
Say it like this
/pstack:why Why is the retry limit 5? Does that reason still hold?

Just asking vs. using it

The same request, typed plainly or with /pstack:why. Here's what changes.

Just askingWith /pstack:why
States a guessed reason as if it were fact.Separates findings, inferences, competing hypotheses and unknowns, each marked with confidence.
Stops after one or two sources turn up nothing.Sends one investigator per evidence source and lists empty ones in Sources Consulted.
Treats the latest commit as the whole story.Traces history with git blame and git log, then reads the PR discussions.

What the document says

8 sections, about 1400 words, 6 min to read. Click a section to read it.

OpeningIt says why explains what forces shaped the code, sets each helper's model, and requires agent mode so MCP tools stay available.

  1. 1Operating PostureTells the AI to act as a careful investigator and follow references/epistemics.md to separate knowledge from inference.
  2. 2Understand the Target and the QuestionPins down the target code and the kind of reason asked. If vague, it states its reading and continues.
  3. 3Establish the Code AnchorRuns git blame, git log and gh pr view first, collecting files, lines, commits and PRs for every investigator.
  4. 4Spawn Parallel InvestigatorsSorts connected MCPs into 7 evidence categories and runs one investigator per category at once. Every skip needs a written reason.
  5. 5SynthesizeSpawns one synthesizer with all findings and null results, the code anchor, the question and the epistemics rules.
  6. 6PresentShows you the synthesizer's answer, lightly edited at most, with its confidence wording untouched.
  7. 7Output FormatWrites findings, inferences, hypotheses, unknowns and one line per source. Before a change, adds Preserve / Change / Avoid / Risk.
  8. 8Common Failure Modes to AvoidWarns against recency bias. The latest commit is rarely the whole reason, so trace further back.

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. Count "found nothing" as a result

    Document the null, don't skip the search.

    Makes the AI
    Every source really gets searched, and empty ones are listed, so you can see what was checked and what is blank.
    Why it works
    AIs skip searches they guess are empty; making the empty result something to hand in leaves no reason to skip.
    Borrow it
    When you ask for a search, add: "Check every log, and give a line 'checked, nothing found' for the clean ones."
  2. Ask for facts and guesses apart

    Be honest about what you know vs what you're inferring.

    Makes the AI
    Cited findings and inferences come in separate parts, so you know which lines you can trust outright.
    Why it works
    A "why" story is easy to smooth over; labeling how sure each line is keeps guesses out of the facts.
    Borrow it
    When you ask why, add: "Put what has a source first, and list your own guesses separately, marked 'guess'."
  3. Say what each source is best at

    Each category below is uniquely positioned to surface one shape of "why"

    Makes the AI
    It looks in chat for live debate and in error logs for failures, instead of giving up after one dry source.
    Why it works
    Pairing each source with what it's best at tells the AI what to expect, and names the gap when one comes back empty.
    Borrow it
    When you ask for research, assign roles: "Docs for usage, GitHub issues for known bugs, the changelog for when it changed."
  4. Make skipping cost a written reason

    Only with an explicit, written justification that goes in the final Sources Consulted.

    Makes the AI
    It won't quietly drop a source; if it skips one, the end of the report says why.
    Why it works
    Having to write the reason down makes shortcuts visible, so the AI only skips when it can defend it.
    Borrow it
    With a checklist, add: "For any item you didn't do, add a line at the end saying why."

Full text

The SKILL.md the AI reads, as written.

descriptionUse for 'why does X work this way', 'why we picked Y', design rationale, regressions, postmortems, or data-backed thresholds. Discovers available MCPs and queries each evidence category (source control, issue tracker, long-form docs, real-time chat, infrastructure observability, error tracking, product analytics warehouse) in parallel, then returns a cited read on decisions and tradeoffs. Use how for runtime behavior.

Why

Investigate the motivation and intent behind code. The companion how skill answers what the code does and how it works. why answers what forces led to its shape.

Each spawn below names a role 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) and a default. 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.

Every spawn is generalPurpose with readonly: false (agent mode). Do not use readonly/Ask mode. It strips MCP access, which disables the MCP-backed investigators and the synthesizer's citation spot-checks. Investigators still shouldn't write anything.

Operating Posture

Operate as a careful, cautious, and precise investigator. Be honest about what you know vs what you're inferring. Read references/epistemics.md for the full confidence framework and phrasing guide. The synthesizer must follow it.

Step 1. Understand the Target and the Question

The target is usually a chunk of code, a pattern, a feature, or a named design decision. The question is usually a design rationale, a tradeoff, a motivating edge case, an external constraint, dead code, or a broad history sweep.

If the target is vague ("why do we do it this way?" with no clear referent), make your best guess from conversation context (open files, recent edits, cursor location, what was just discussed). State your interpretation briefly so the user can redirect if you're off, then proceed.

Step 2. Establish the Code Anchor

Before spawning investigators, build the seed context inline: file paths and line ranges, key symbols (functions, classes, constants), the last few commits touching the target, PR numbers from merge commits (pattern (#1234) in the subject line), and any linked ticket IDs. Run git blame -L <start>,<end> <file> for last-touch commits, git log --follow -p -- <file> for full history with patches through renames, git log --oneline -20 -- <file> for recent commits with PR numbers visible, and git log -1 --format=%B <commit> to extract PR numbers. Then pull the PR bodies and discussion for any substantive commit: gh pr view <number> --json title,body,author,createdAt,mergedAt,labels,closingIssuesReferences,comments,reviews. This anchor goes to every investigator and to the synthesizer.

Step 3. Spawn Parallel Investigators

Default to the full parallel investigation. The goal is a complete coverage map, not a minimal one. Document the null, don't skip the search.

Discovery

Before spawning investigators, list the MCP servers connected to your harness. Use the available-tools map when present. In Cursor, you can also inspect the mcps/ directory it exposes for enabled MCP servers. In other harnesses, MCP tools usually appear in your tool list with the server name in the tool name (for example mcp__<server>__<tool> in Claude Code).

Map each available MCP to one evidence category:

  1. Source control history
  2. Issue / ticket tracker
  3. Long-form documents
  4. Real-time team chat
  5. Infrastructure observability
  6. Error / exception tracking
  7. Product analytics warehouse

Source control is always available through git and gh. For the other six, classify using the MCP name, server instructions, tool names, and resource descriptors. If an MCP could fit more than one category, choose the one matching its primary evidence. Record ambiguous cases in the coverage map.

Spawn one investigator per category that has a matching MCP, all in a single message so they run concurrently, each owning exactly one tool or MCP. Don't ask one agent to cover multiple MCPs. model: the why investigators line, default grok-4.7-xhigh-fast.

Each investigator's prompt is references/investigator-prompt.md filled in, plus:

  • the category playbook references/sources/<source>.md for the selected MCP, adapted from the examples in references/source-playbook.md
  • references/sources/incident-postmortem.md if the target code looks defensive (null checks, retry logic, timeout handling, rate limiting, feature flags, egress guards, OOM handlers)
  • the code anchor and the user's original question

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 investigator yourself, one after another.

Investigator roster, one per available evidence category

Each category below is uniquely positioned to surface one shape of "why", shown after "Best at". Use it to know what to expect back, to name a gap when a category returns empty, and, only in the rare provably-irrelevant case, to justify a skip.

  1. Source control (git history, gh for PRs, code comments, tests). Always spawn, the only guaranteed source. Best at implementation-time rationale captured during review.
  2. Issue / ticket tracker (e.g. Linear, Jira, GitHub Issues, Plane, Shortcut MCP). Best at the product or business forcing function. Strongest when the why is external to engineering.
  3. Long-form documents (e.g. Notion, Confluence, Google Docs, Coda MCP). Best at long-form design rationale, written out before it becomes code.
  4. Real-time team chat (e.g. Slack, Discord, Microsoft Teams, Mattermost MCP). Best at real-time deliberation that never reached a doc. Especially important when the source control, ticket, and doc paper trail is thin.
  5. Infrastructure observability (e.g. Datadog, New Relic, Honeycomb, Grafana, Splunk MCP). Best at infrastructure and runtime reality that motivated the code. Strongest when the target reacts to an infra signal (timeouts, retries, rate limits, circuit breakers).
  6. Error / exception tracking (e.g. Sentry, Rollbar, Bugsnag, Airbrake MCP). Best at the specific exceptions and error trajectories that motivated defensive or corrective code. Strongest for catch blocks, null guards, type checks, retries, and other defenses.
  7. Product analytics warehouse (e.g. Databricks, Snowflake, BigQuery, ClickHouse, dbt, Redshift MCP). Best at product and data reality that shaped the code. Strongest for flag-gated code, experiment-driven ships, data migrations, and "where did this number come from" questions.
When to skip an investigator

Only with an explicit, written justification that goes in the final Sources Consulted. Two valid reasons:

  • No MCP is available for that category in this environment. Flag it as a gap, not a choice: "Real-time team chat skipped. No matching MCP available, so the conversational record was not searchable."
  • The source is provably irrelevant, not just "probably irrelevant." A high bar: "Error / exception tracking skipped. Target is a build-time script with no runtime code path."

If your scope assessment suggests a single-commit trivial target where the PR description already contains the complete answer, you may answer inline only after confirming all seven available category searches would be redundant. Say so explicitly. This should be rare.

Step 4. Synthesize

Spawn one synthesizer. model: the why synthesizer line, default claude-opus-5-5-xhigh. It gets:

  1. The investigator findings, including any null results and any categories skipped with justification
  2. The code anchor
  3. The user's original question
  4. The epistemics framework from references/epistemics.md
  5. The synthesizer prompt template from references/synthesizer-prompt.md

Step 5. Present

Present the synthesizer's output to the user. You may lightly edit for clarity or add context from the conversation, but do not rewrite the confidence language.

Output Format

The structure is the one in references/synthesizer-prompt.md: The Question, The Code in Question, What We Found, What We Can Reasonably Infer, Competing Hypotheses, What We Don't Know, Sources Consulted, Confidence Summary. Adapt as needed, but keep the confidence separation intact, and keep Sources Consulted as one line per investigator, including the ones that returned nothing or were skipped, with the reason.

After Sources Consulted, if the user's why question is a precursor to changing this code, convert the lineage findings into a Preserve / Change / Avoid / Risk constraint set for planning the change.

Common Failure Modes to Avoid

  • Recency bias. Assuming the most recent commit is authoritative. The current shape is often the accretion of many earlier decisions. Trace back.

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.