Agent skill · research science · cursor
why
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 this skill is useful
Adds a structured approach to gather and synthesize historical evidence about design decisions, which the AI wouldn't reliably generate on its own.
What it needs
About 6k tokens when loaded. Last updated 2026-08-06. 2,555 stars on the source repository.
What this skill does
Why 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. Each spawn below names a role line in the pstack-models.mdc rule and a default. Set model to that line's value, or to the default if the rule or the line is missing. Leave model unset when the value is auto or inherit-parent. If the Task 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. 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. 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, 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. Pull PR bodies and discussion via gh for any substantive commits: Capture this as seed context (file paths, symbols, commits, PR numbers, linked ticket IDs). Pass it to the investigators. Step 3. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills cursor/why