why · diff

git:20261008.31a131d to git:20261011.042ae70

30 added, 89 removed. Audit A to A.

---

name: why

description: "Use 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

Read [the pstack-t3 runtime](../pstack-runtime/SKILL.md) before spawning workers, choosing models, scheduling, or isolating work. It maps those steps onto T3's orchestrator tools.

- Investigate the motivation and intent behind code.

- Companion to the `how` skill. `how` answers what the code does and how it works. `why` answers what forces led to its shape.

+ 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. Resolve its seat per the [runtime's Roles section](../pstack-runtime/SKILL.md#roles) and spawn with `delegate_task`. Omit `target` for an `inherit` seat. If T3 rejects a target, fall back per the runtime and say which seat changed.

[The runtime's Modes section](../pstack-runtime/SKILL.md#modes) sets the mode lines of every brief this skill writes and how its spawns run in light mode.

+ Every spawn is `delegate_task` with `role: "research"` and a read-only brief that says "Do not edit files, commit, or push." **Do not lower the child's runtime mode to strip tools.** The MCP-backed investigators and the synthesizer's citation spot-checks need their MCP tools, so the brief carries the read-only constraint.

## 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

- Parse what the user is asking. 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.

+ 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, 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, anchor the investigation in concrete code. You need:

- - The relevant file path(s) and line range(s)

- - The key symbols (function names, class names, constants)

- - An initial commit list. The last few commits touching the target.

- - PR numbers from merge commits (pattern `(#1234)` in the subject line)

- Build this inline.

- ```bash

- # Blame target lines for last-touch commits

- git blame -L <start>,<end> <file>

- # Full file history, with patches, through renames

- git log --follow -p -- <file>

- # Last N commits touching the file, PR numbers visible

- git log --oneline -20 -- <file>

- # Extract PR numbers from a commit message

- git log -1 --format=%B <commit>

- ```

- Pull PR bodies and discussion via `gh` for any substantive commits:

- ```bash

- gh pr view <number> --json title,body,author,createdAt,mergedAt,labels,closingIssuesReferences,comments,reviews

- ```

- Capture this as seed context (file paths, symbols, commits, PR numbers, linked ticket IDs). Pass it to the investigators.

+ 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 posture)

+ ## Step 3. Spawn Parallel Investigators

- **Default to the full parallel investigation.**

+ **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 available in this session from your own tool list. MCP tools carry their server in the name (`mcp__<server>__<tool>` or `<server>.<tool>`, depending on the host). Read the server instructions the host shows alongside them. If the host has a deferred-tool search, query it for each category below before concluding a category has no MCP. A server listed as needing authentication or failing to connect is a gap, not an absent source. Name it in the coverage map so the user can fix it.

T3 always provides the `t3-code` server. It carries orchestration and thread history, not evidence about the code, so it maps to no category.

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.

- Aim for a complete **coverage map**, not a minimal one. Document the null, don't skip the search.

- Launch all matching investigators in a single message so they run concurrently. Don't ask one agent to cover multiple MCPs.

- Child config (each):

- - `delegate_task` with `mode: "async"`, `role: "research"`, and `title: "why investigator: <category>"`

- - `target`: the `why investigators` role's seat

- - A read-only brief: "Do not edit files, commit, or push." Investigators need their MCP tools, so the brief carries the read-only constraint. Do not lower the child's runtime mode to strip tools.

- - Name the exact MCP server the investigator owns. A child on another provider may not have the same MCP servers configured. Tell it to confirm its server's tools are present before searching, and to return `MCP unavailable in this child: <server>` instead of a null result when they are not. Respawn that investigator once on an `inherit` seat, which shares this thread's provider and its MCP configuration, and record the swap.

- Each investigator gets:

- 1. The base prompt from `references/investigator-prompt.md`

- 2. The category playbook `references/sources/<source>.md` for the selected MCP, adapted from the examples in `references/source-playbook.md`

- 3. The cross-cutting `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)

- 4. The code anchor from Step 2 (file paths, symbols, commit hashes, PR numbers, ticket IDs)

- 5. The user's original question

- ### Investigator roster. One per available evidence category

- Spawn one investigator per category that has a matching MCP. Each owns exactly one tool or MCP.

- Each entry names the category and the kind of "why" it uniquely surfaces. Use it to know what to expect back, how to name a gap when a category returns empty, and (only in the rare provably-irrelevant case) to justify a skip.

- 1. **Source control investigator**. Git history, `gh` for PRs, code comments, tests. Always spawn. The only guaranteed source. Best at surfacing *implementation-time rationale captured during review*.

- 2. **Issue / ticket tracker investigator** (e.g. Linear, Jira, GitHub Issues, Plane, Shortcut MCP). Best at surfacing *the product or business forcing function*. Strongest when the why is external to engineering.

+ 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. `target`: the `why investigators` role's seat. Use `mode: "async"` and `title: "why investigator: <category>"`.

- 3. **Long-form documents investigator** (e.g. Notion, Confluence, Google Docs, Coda MCP). Best at surfacing *long-form design rationale*. Where the why is written out before it becomes code.

+ Name the exact MCP server the investigator owns. A child on another provider may not have the same MCP servers configured. Tell it to confirm its server's tools are present before searching, and to return `MCP unavailable in this child: <server>` instead of a null result when they are not. Respawn that investigator once on an `inherit` seat, which shares this thread's provider and its MCP configuration, and record the swap.

- 4. **Real-time team chat investigator** (e.g. Slack, Discord, Microsoft Teams, Mattermost MCP). Best at surfacing *real-time deliberation that never reached a doc*. Especially important when the source control, ticket, and doc paper trail is thin.

+ 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

- 5. **Infrastructure observability investigator** (e.g. Datadog, New Relic, Honeycomb, Grafana, Splunk MCP). Infra/runtime view. Best at surfacing *infrastructure and runtime reality that motivated the code*. Strongest when the target reacts to an infra signal (timeouts, retries, rate limits, circuit breakers).

+ ### Investigator roster, one per available evidence category

- 6. **Error / exception tracking investigator** (e.g. Sentry, Rollbar, Bugsnag, Airbrake MCP). Best at surfacing *the specific exceptions and error trajectories that motivated defensive or corrective code*. Strongest for catch blocks, null guards, type checks, retries, and other defenses.

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

- 7. **Product analytics warehouse investigator** (e.g. Databricks, Snowflake, BigQuery, ClickHouse, dbt, Redshift MCP). Product/data view. Best at surfacing *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.

+ 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 skip with an **explicit, written justification** that goes in the final "Sources Consulted" section. Two valid reasons:

+ 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 this as a gap, not a choice. Example: "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. Example: "Error / exception tracking skipped. Target is a build-time script with no runtime code path."

+ - **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 child:

- - `delegate_task` with `role: "research"` and `title: "why synthesizer"`. Use `mode: "async"` and collect it per [the runtime's Delegation step 5](../pstack-runtime/SKILL.md#delegation), or `mode: "wait"` when presenting is the only step left.

- - `target`: the `why synthesizer` role's seat

- - A read-only brief. The synthesizer's quality check spot-verifies citations, which can require MCP access, so keep its tools and put "do not edit files, commit, or push" in the brief.

- The synthesizer gets:

+ Spawn one synthesizer. `target`: the `why synthesizer` role's seat. Use `title: "why synthesizer"`. Use `mode: "async"` and collect it per [the runtime's Delegation step 5](../pstack-runtime/SKILL.md#delegation), or `mode: "wait"` when presenting is the only step left. It gets:

1. The investigator findings, including any null results and any categories skipped with justification

- 2. The code anchor from Step 2 (file paths, symbols, commit hashes, PR numbers, ticket IDs)

+ 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

- Take the synthesizer's output and present it to the user. You may lightly edit for clarity or add context from the conversation, but **do not rewrite the confidence language**.

+ 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 output 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.

+ 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 the Sources Consulted block, if the user's `why` question is a precursor to actually changing this code, convert the lineage findings into a Preserve / Change / Avoid / Risk constraint set suitable for planning the change.

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

- ## Reference Files

- - `references/epistemics.md`. Confidence tiers and phrasing guide. The synthesizer must follow it.

- - `references/investigator-prompt.md`. Base prompt template for investigator subagents.

- - `references/source-playbook.md`. Index pointing at the category playbooks below.

- - `references/sources/*.md`. One self-contained example playbook per category, plus cross-cutting `incident-postmortem.md`. Give an investigator the single file that matches its category and adapt it to the available MCP.

- - `references/synthesizer-prompt.md`. Prompt template for the synthesizer subagent, including the output format.