why

Files (14)

• SKILL.md
• openai.yaml · agents/
• epistemics.md · references/
• investigator-prompt.md · references/
• source-playbook.md · references/
• code-archaeology.md · references/sources/
• databricks.md · references/sources/
• datadog.md · references/sources/
• incident-postmortem.md · references/sources/
• linear.md · references/sources/
• notion.md · references/sources/
• sentry.md · references/sources/
• slack.md · references/sources/
• synthesizer-prompt.md · references/

SKILL.md (first lines)

# Why

Investigate the motivation and intent behind code. Why was it built this way? What edge cases were considered? What product, business, or operational constraints shaped the design? What alternatives were rejected, and why?

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

## How this skill works

Historical context may live in seven evidence categories: source control history, issue or ticket tracking, long-form documents, real-time team chat, infrastructure observability, error or exception tracking, and product analytics warehouses. The question alone cannot tell you which category holds the answer. At run time, list the available MCPs, map each to a category, search all seven categories in parallel, and synthesize the results with explicit confidence calibration. Treat null results as evidence about how the decision was made and report them alongside positive findings. Search every available category by default.

## Operating posture

Check each claim against the record and state its confidence precisely. Treat the available evidence as fragments of a historical record. When the record is thin, say so.

Collect the evidence before writing a narrative. Follow what the records support instead of selecting evidence for a story you have already chosen.

Prefer an exact quote and citation to a smooth paraphrase. A reader should be able to follow any claim back to its source and verify it in under a minute.

Treat the evidence you find as a sample of a larger, partly inaccessible record. Before concluding, identify what you would expect to find if an alternative explanation were true and whether you searched for it.

Document every gap, including cold threads, unsearchable sources, and unanswered questions. Do not replace a gap with an authoritative-sounding guess.

Use "appears to", "likely", or "suggests" when evidence is indirect. The synthesizer must preserve language that matches the confidence level.

Read code to establish what it does. Do not infer intent from its shape; code rarely records why it exists.

## Core epistemics

Historical evidence is fragmented. Tickets go stale, chat threads get deleted, and commit messages can be wrong. People change their minds between a PR description and its implementation, and the original author may have left the company.

Distinguish what the record states from what you infer. Show the evidence and mark its confidence. Leave the judgment to the user.

Cite every claim about intent with a specific commit hash, PR number, ticket ID, doc URL, chat permalink, or code comment. Label any claim without such a citation as inference.

Use "appears to" in place of "because" when evidence is indirect. Reserve confident language for direct, explicit evidence.

Show both accounts when sources contradict each other. Do not quietly select the one that fits your narrative.

If none of the searched sources answers a question, say, "we couldn't find out why." Do not substitute a confident guess.

When the evidence supports several explanations, present each one with its supporting evidence and let the user triangulate.

Code that makes sense today may have been written for reasons that no longer apply, or for no good reason. Do not retrofit intent.

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** usually falls into one of these forms:

- "Why was X designed this way?" Design rationale.
- "Why do we do X instead of Y?" Tradeoff or alternatives.
- "What edge cases motivated this?" Defensive reasoning.
- "What business or product constraint led to this?" External forcing function.
- "Why does this code still exist?" Existing or dead code.
- "What's the history of X?" Broad history.

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 list of the last few commits touching the target
- PR numbers from merge commits (pattern `(#1234)` in the subject line)

Build the anchor in the lead agent and give the same information to every investigator.

```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 the file paths, symbols, commits, PR numbers, and linked ticket IDs as seed context. Pass it to the investigators so they do not repeat this search.

## Step 3. Spawn parallel investigators

Search every available evidence category in parallel by default. Each category lives in a different kind of system, and the question alone cannot reveal which one holds the answer.

### Discovery

Before spawning investigators, list the available MCPs from the Cursor environment. Use the available-tools map when present. Otherwise inspect the `mcps/` directory Cursor exposes for enabled MCP servers.

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.

Build a complete **coverage map**. A null result from an issue tracker is evidence that the decision was not ticketed. Run the search, then document any null result.

Launch all matching investigators in a single message so they run concurrently. Assign one category and one MCP to each investigator so it can specialize in that tool's query vocabulary and result shape.

Subagent config (each):
- `subagent_type`: `generalPurpose`
- `model`: your configured why-investigators model (default `grok-4.6-fast-xhigh`)

From hellsan631/skills, MIT.

More from hellsan631/skills