skills.rest
gmackie
gmackieCOMMUNITY
Explore all skills by this author →
Website𝕏@grahammackieGitHub

why

Investigate design rationale behind code by querying seven evidence sources in parallel.

Updated Mar 27, 2026
Search Tags:#research#MCP#design rationale#git history#postmortem#code archaeology#evidence investigation
One-click install
npx skills add https://github.com/gmackie/agent-skills --skill why-gmackie
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: why
Source: https://github.com/gmackie/agent-skills/tree/main/skills/why
Command: npx skills add https://github.com/gmackie/agent-skills --skill why-gmackie

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Code rarely explains why it exists. This Skill reconstructs the motivation, tradeoffs, and constraints behind a piece of code by searching historical evidence across source control, issue trackers, docs, chat, observability, error tracking, and analytics systems, then returns a cited, confidence-calibrated answer instead of a confident guess. ## Core Features & Use Cases - Parallel evidence investigation: Discovers available MCPs at runtime, maps them to seven evidence categories, and spawns one investigator subagent per category to search concurrently. - Confidence-calibrated synthesis: A dedicated synthesizer merges findings into Direct, Supported, Inferred, Speculative, and Unknown tiers with explicit citations and documented gaps. - Use Case: Ask why a retry limit is set to 3 in a backend service. The Skill traces the PR, linked ticket, Slack incident thread, Datadog monitor, and Sentry spike around the ship date, then reports which claims are directly evidenced and which are inference. ## Quick Start Ask the agent why a specific function or design decision in the current codebase was made and request a cited historical investigation.

Frequently Asked Questions about why

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

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

Anchor the investigation with git blame and git log on the target lines, pull PR context via gh, then search issue trackers, docs, chat, and telemetry for the rationale. This Skill automates that by spawning one investigator per evidence category in parallel.

What is the difference between the why and how skills?▼

The how skill explains what code does and how it works at runtime. The why skill explains the forces that led to its shape: design rationale, rejected alternatives, business constraints, and incident history, backed by citations.

Which MCP servers does this investigation support?▼

It maps available MCPs to seven categories: git/gh for source control, Linear or Jira for tickets, Notion or Confluence for docs, Slack for chat, Datadog for observability, Sentry for error tracking, and Databricks or Snowflake for analytics.

What happens if some evidence sources are unavailable?▼

Missing MCPs are documented as explicit gaps in the Sources Consulted section, not silently skipped. Null results from searched categories are reported as first-class evidence about how the decision was made.

Can the skill cite code as evidence of intent?▼

No. The epistemics framework explicitly forbids citing code as evidence for its own motivation. Intent claims require external sources like PR discussions, tickets, comments, or chat threads; otherwise they are labeled as inference.

Related Skills

Explore More Software Engineering Skills→
nielsmadannielsmadan
1

review-history

Analyze Git history to identify code changes and regressions.

Community
Intermediate
li3pli3p

refactor-safe

Plan internal code refactoring while preserving public API signatures.

Community
Intermediate
liujiayi3703liujiayi3703

yes

Provide empathetic praise and humorous criticism for team motivation.

Community
Advanced
LSDIPPOLLCLSDIPPOLLC

linear-adr

Create and manage Architecture Decision Records as Linear issues with linked documents.

Official
Intermediate