but-why

Investigates design rationale behind code by querying git history, tickets, docs, chat, and observability sources in parallel.

Updated Sep 13, 2026
One-click install
npx skills add https://github.com/petemcw/farseer --skill but-why-petemcw
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: but-why
Source: https://github.com/petemcw/farseer/tree/main/skills/but-why
Command: npx skills add https://github.com/petemcw/farseer --skill but-why-petemcw

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Code rarely explains why it exists. This Skill answers "why does this code work this way" questions by searching historical evidence across source control, issue trackers, docs, chat, and monitoring tools, then returning a cited, confidence-calibrated answer instead of a guess. ## Core Features & Use Cases - Parallel evidence investigation: Spawns one investigator per evidence category (git/PRs, Jira, Confluence, Slack, Datadog, Sentry, data warehouses) based on available MCPs, each with a source-specific playbook. - Confidence-tiered synthesis: A synthesizer agent classifies every claim as Direct, Supported, Inferred, Speculative, or Unknown, with verbatim citations and explicit documentation of gaps and contradictions. - Use Case: Ask "why is this retry limit set to 3?" and receive a report tracing the PR discussion, linked incident postmortem, and Slack thread that motivated the defensive code, plus a Preserve/Change/Avoid/Risk constraint set if you plan to modify it. ## Quick Start Ask why a specific function, threshold, or pattern in your codebase exists and let the skill investigate the historical evidence across your connected tools.

Frequently Asked Questions about but-why

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I find out why a piece of code was written a certain way?▼

Ask a why question about the target code and the skill anchors it via git blame and log, then spawns parallel investigators across source control, tickets, docs, chat, and monitoring tools. A synthesizer returns a cited answer with confidence tiers.

What is the difference between but-why and but-how?▼

but-how explains what the code does and how it works at runtime. but-why explains the forces that led to its shape, using historical evidence from commits, PRs, tickets, docs, and conversations.

Which tools and MCPs does code rationale investigation support?▼

Git and the gh CLI are always used for source control history. Optional MCP categories include Jira or Linear for tickets, Confluence or Notion for docs, Slack for chat, Datadog for observability, Sentry for errors, and Snowflake or BigQuery for analytics.

What happens when no evidence exists for why code was written?▼

The skill reports an explicit Unknown rather than guessing. It documents exactly which sources and queries were searched, what returned nothing, and which people would likely know the answer.

Can investigation results help plan changes to legacy code?▼

Yes. After the evidence report, the skill converts lineage findings into a Preserve, Change, Avoid, and Risk constraint set suitable for planning modifications without breaking the original intent.