Why

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 spreads across 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. You cannot predict from the question alone which one holds the answer, so the skill enumerates available MCPs at run time, maps each to a category, queries all seven in parallel, then synthesizes with explicit confidence calibration. Null results from searched categories are first-class evidence about how the decision was made; report them alongside positive findings. The default is coverage, not minimalism.

Operating Posture

Operate as a careful, cautious, precise investigator. Think like a detective piecing together a historical case from fragmentary records. When the record is thin, say so.

Concretely:

• Evidence before narrative. Collect the pieces first, then see what story they support. Never pick a story and recruit the evidence that fits it.
• Precision over polish. Prefer the exact quote and citation over a smooth paraphrase. A reader should be able to follow any claim back to its source and verify it in under a minute.
• Consider what you haven't seen. The evidence you find is a sample, not the whole truth. Before concluding, ask what you would expect to see if an alternative explanation were true, and whether you looked for it.
• Name the gaps. If a thread goes cold, a source isn't searchable, or a question has no answer, document the gap. Don't paper it over with an authoritative-sounding guess.
• Hedge on purpose. When evidence is indirect, your language should signal it ("appears to", "likely", "suggests"). Confidence-matching phrasing is a feature of the output, not a stylistic choice the synthesizer may override.
• No shortcut by code-reading. The code tells you what it does, rarely why it exists. Resist inferring intent from code shape.

This posture is the working method, not a disclaimer.

Core Epistemics

This skill builds a patchwork understanding from fragmented historical evidence. Tickets go stale. Chat threads get deleted. Commit messages lie. People change their minds between the PR description and the implementation. The original author may have left the company.

Be ruthlessly honest about what you know versus what you're inferring. The goal is not a satisfying story; it is to surface evidence, calibrate confidence, and let the user decide.

Principles:

• Cite everything. Every claim about intent should reference a specific commit hash, PR number, ticket ID, doc URL, chat permalink, or code comment. If you can't cite it, it's inference, not fact, and must be labeled as such.
• Prefer "appears to" over "because". Hedge when evidence is indirect. Reserve confident language for direct, explicit evidence.
• Surface contradictions. If two sources disagree, show both. Don't quietly pick the one that fits your narrative.
• Acknowledge gaps. If a question has no answer in any source you searched, say so. An honest "we couldn't find out why" beats a confident guess.
• Multiple hypotheses are valid. When the evidence fits several stories, present them all with the evidence for each. Let the user triangulate.
• Beware rationalization. Code that makes sense today may have been written for reasons that no longer apply, or for no good reason at all. Don't 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 is usually one of:

• "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?" Dead-code territory.
• "What's the history of X?" Broad archaeological 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. It's cheap, and every investigator needs it.

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

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 so they don't rediscover it.

Step 3. Spawn Parallel Investigators (default posture)

Default to the full parallel investigation. Each evidence category lives in a different kind of system, and you cannot tell from the question alone which one holds the answer without looking. So look across every available category, in parallel, by default.

Discovery

Before spawning investigators, take stock of what evidence this environment actually has.

In this repo, start from references/sources/rove-local.md. Rove keeps its decision record on disk and in the daemon: ADRs, docs/design/ notes, the daemon issue store, the changelog, HANDOFF.md, and wisp. That playbook lists each one with the command that searches it. None of them is an MCP, and the vendor playbooks beside it (Linear, Notion, Slack, Sentry, Datadog, Databricks) document tools this repo does not have — they are templates for repos that do.

Then check for MCP servers in the current session's tool list, and map each one you find to an 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. A null result from an issue tracker is evidence the decision was not ticketed, a useful fact in itself. Document the null, don't skip the search.

Launch all matching investigators in a single message so they run concurrently. One investigator per category lets each specialize in one tool's query vocabulary and result shape. Don't ask one agent to cover multiple MCPs.

Subagent config (each): spawn with the Agent tool, subagent_type: "general-purpose". Investigators inherit the session model; pass model only when a cheaper tier clearly fits. Do not use a read-only agent type — it can strip MCP access, which disables MCP-backed investigators entirely. Keep modes uniform even though the local-source investigators would be safe read-only. Investigators still must not write anything; that is a posture, not a sandbox.

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 lists what the category physically contains 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. Every category overlaps, but each owns a kind of evidence the others cannot recover.

0. Local decision-record investigator (this repo). ADRs, docs/design/, the daemon issue store, CHANGELOG.md, HANDOFF.md, wisp. Always spawn; in this repo it is the category most likely to hold an explicit, dated, argued answer. Playbook: sources/rove-local.md. Best at surfacing the decision as its author wrote it down — an ADR's Context/Decision/Consequences, a design note stating a constraint bluntly, a keybinding argument recorded in keybinding-decisions.md. When it returns empty, that is real evidence the decision was never written up.

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. PR descriptions stating the problem, review threads debating alternatives, inline comments encoding non-obvious constraints, test names that encode motivating edge cases, and commit messages linking tickets or incidents. Most trustworthy because it ties directly to the diff that shipped.

2. Issue / ticket tracker investigator (e.g. Linear, Jira, GitHub Issues, Plane, Shortcut MCP). Tickets, project docs, status updates, spec attachments. Best at surfacing the product or business forcing function. Customer requests ("Acme needs X for their SOC2 audit"), compliance deadlines, parent-initiative framing ("Q3 enterprise readiness"), ticket-level scope changes, and labels that categorize the motivation (customer:*, incident-followup, compliance, perf-regression). Strongest when the why is external to engineering.

3. Long-form documents investigator (e.g. Notion, Confluence, Google Docs, Coda MCP). PRDs, specs, RFCs, design docs, ADRs, postmortems, team pages, meeting notes. Best at surfacing long-form design rationale. Problem statements, explicit "alternatives considered" and "rejected approaches" sections, strategy documents that set priorities, ADRs with finalized decisions, and postmortem action items that tie directly to code. Where the why is written out before it becomes code.

4. Real-time team chat investigator (e.g. Slack, Discord, Microsoft Teams, Mattermost MCP). Feature-name and symbol searches, PR URL mentions, incident channels (#sev-*, #incident-*), author-handle activity around the ship date. Best at surfacing real-time deliberation that never reached a doc. Fire-drill decisions during incidents, Q&A between the PR author and reviewers, casual "we decided X because Y" threads, and rationale for small changes that didn't warrant a PRD. Especially important when the source control, ticket, and doc paper trail is thin.

5. Infrastructure observability investigator (e.g. Datadog, New Relic, Honeycomb, Grafana, Splunk MCP). Metrics, monitors, dashboards, logs, APM traces, formal incidents. Infra/runtime view. Best at surfacing infrastructure and runtime reality that motivated the code. Monitor thresholds whose numbers match code constants, metric spikes in the window right before a PR merge, dashboards created as postmortem action items, incident timelines that reference the target. Strongest when the target reacts to an infra signal (timeouts, retries, rate limits, circuit breakers).

6. Error / exception tracking investigator (e.g. Sentry, Rollbar, Bugsnag, Airbrake MCP). Issues, events, stack traces, releases. Best at surfacing the specific exceptions and error trajectories that motivated defensive or corrective code. Stack traces that pass through the target function, issues whose first-seen/last-seen windows bracket the PR ship date, release correlations that show an error stopping at a specific version. Strongest for catch blocks, null guards, type checks, retries, and other defenses.

7. Product analytics warehouse investigator (e.g. Databricks, Snowflake, BigQuery, ClickHouse, dbt, Redshift MCP). Product-analytics events, experiment and feature-flag exposure tables, usage and billing events, query history, warehouse telemetry. Product/data view. Complements infrastructure observability by covering user behavior and data reality around the ship date rather than infra metrics. Best at surfacing product and data reality that shaped the code. Feature-usage trajectories (a step-function ramp from zero is strong evidence that this PR launched it), experiment/flag exposure data tied to ship decisions, pre-ship distributions that reveal where a threshold constant came from (e.g., limit = 128 * 1024 matching the p99 of an upload-size column), and data-pipeline scale evidence for migrations/backfills. Strongest for flag-gated code, experiment-driven ships, data migrations, and "where did this number come from" questions.