why
Find why code is the way it is, from its history and every evidence source this session can query, with citations. Use for 'why does X work this way', 'why did we pick Y', regressions and postmortems. Use how for runtime behavior.
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- tip
- finds why the code is the way it is, with cited evidence | why does * work this way | why did we pick | why did we choose | design rationale | postmortem | post mortem
- card
- Understand what is there | 2 | Explains why something was built this way, with a cited read of the decisions and tradeoffs from source control, issues and docs. | Reach for it when you need the rationale, or are looking into a regression. | op: the operator; plain: a step of `architect`
- name
- why
- description
- Find why code is the way it is, from its history and every evidence source this session can query, with citations. Use for 'why does X work this way', 'why did we pick Y', regressions and postmortems. Use how for runtime behavior.
02 资源文件 14
- 参考文档feature.json148 B
- 参考文档references/epistemics.md6.6 KB
- 参考文档references/investigator-prompt.md5.4 KB
- 参考文档references/source-playbook.md1.3 KB
- 参考文档references/sources/code-archaeology.md1.4 KB
- 参考文档references/sources/databricks.md6.8 KB
- 参考文档references/sources/datadog.md4.9 KB
- 参考文档references/sources/incident-postmortem.md372 B
- 参考文档references/sources/linear.md2.9 KB
- 参考文档references/sources/notion.md2.8 KB
- 参考文档references/sources/sentry.md2.0 KB
- 参考文档references/sources/slack.md1.3 KB
- 参考文档references/synthesizer-prompt.md7.0 KB
- 参考文档verify.md487 B
03 SKILL.md 正文
Why
Source: pstack, pstack/skills/why/SKILL.md
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.
Every spawn below is one call of the Agent tool (or, with no subagent tool, do it in this thread, working from the same prompt), this one with prompt set to the prompt built from its template:
{
"subagent_type": "Explore",
"description": "why investigator",
"prompt": "The prompt, built from its template.",
"run_in_background": false
}
The type is Explore: it is started with no Edit, Write or NotebookEdit tool and keeps this session's MCP tools, which the MCP-backed investigators and the synthesizer's citation spot-checks need. It runs on this session's model at this session's effort. No model, no effort and no isolation, for an investigator or the synthesizer: there is no model per role here. The synthesizer's call is the same with the description why synthesizer.
A step starts at most ten subagents. The seven categories below are the most this skill starts at once.
The templates and the source playbooks are beside this file, in references/.
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, 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 this session has. Claude Code names their tools mcp__<server>__<tool>, and another harness by its own rule. If your harness defers a tool, load it first: in Claude Code, with ToolSearch. A server that still needs authorizing is not available: say so in the coverage map, and do not ask the user for a token.
Map each available MCP to one evidence category:
- Source control history
- Issue / ticket tracker
- Long-form documents
- Real-time team chat
- Infrastructure observability
- Error / exception tracking
- 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.
Each investigator's prompt is references/investigator-prompt.md filled in, plus:
- the category playbook
references/sources/<source>.mdfor the selected MCP, adapted from the examples inreferences/source-playbook.md references/sources/incident-postmortem.mdif 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
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.
- Source control (git history,
ghfor PRs, code comments, tests). Always spawn, the only guaranteed source. Best at implementation-time rationale captured during review. - 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.
- Long-form documents (e.g. Notion, Confluence, Google Docs, Coda MCP). Best at long-form design rationale, written out before it becomes code.
- 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.
- 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).
- 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.
- 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. It gets:
- The investigator findings, including any null results and any categories skipped with justification
- The code anchor
- The user's original question
- The epistemics framework from
references/epistemics.md - 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.
04 同仓库更多 Skills
no-key
A skill its skills.json lists as hidden that a model may still call by itself, kept broken so the lint is seen to catch it.
fake-skill
A FAKE skill in a FAKE tree, named for its folder until the test renames the folder.
extra-key
A skill its skills.json does not list as hidden that a model still cannot call, kept broken so the lint is seen to catch it.
unslop
Cut AI tells from writing. Use when the user says text reads like AI, asks to unslop it, or before prose ships to people.
technical-writing
Write or review docs, READMEs, RFCs, PR descriptions and commit messages to a layered standard: Diataxis structure, Google developer style, STE rules and Global English.
verify-jstack
Drive jstack's commands (jbus, jmerge, jgauge, install.sh) the way a user does, inside a throwaway sandbox with stand-ins for T3 Code and GitHub, and keep the evidence. Use to prove a change to jstack works in the real commands and not only in its tests, before a pull request claims it does.