why

why — code archaeology for Claude Code

Recover the intent behind a piece of code, not just what it does.

why is a Claude Code skill that turns the question "why does this code exist?" into a disciplined investigation: it walks the file's git history, maps commits to PRs, pulls the ticket and chat discussion that shaped each PR, and hands back a self-contained HTML report you can refer to later.

It runs on demand when you type /why, and (more importantly) proactively — Claude reaches for it on its own before editing unfamiliar, legacy, or fragile code, so a change doesn't silently undo an earlier fix.

---

The problem

Code tells you what it does. It rarely tells you why it does it that way. The "why" lives in history: the commit that introduced it, the PR where it was debated, the Slack thread where someone said "we have to special-case this or the webhook retries forever." If you change the code without knowing that, you reintroduce the bug an earlier change deliberately fixed.

Doing this manually is tedious: git blame, walk back through commits, fish out PR numbers, read review comments, hunt for the ticket, search Slack, cross-reference everything. It's exactly the kind of work a model is good at — if it has a disciplined process to follow. That's what this skill is.

---

What it does (in 10 steps)

1. Scope the target — file + line range / specific symbol.
2. git blame + git log -L to find the introducing commit and the most recent significant (behavioral) change. Also runs find_reverts.py --lines to detect revert / re-apply chains within the line range.
3. Map commits → PRs via gh api (and search-fallback for squash-merge SHAs).
4. Read PR review discussion (humans filtered from bots like CodeRabbit / kodiakhq).
5. Follow the linked tickets — system-agnostic. Recognizes GitHub Issues, Linear, Jira, Asana, Notion, and "any URL referenced in the PR body."
6. Search team chat (Slack via MCP today; the pattern extends to any chat MCP).
7. Map structural callers with find_callers.py — namespace-aware so it doesn't drown in generic-name noise.
8. Map frequent authors with find_authors.py — including Co-authored-by: trailers, with pre-computed gravatar URLs. --lines scopes to a method when you've narrowed.
9. Map co-churn (code-morbidity) with co_churn.py — files that historically change in the same commits as your target. Conditional on ≥3 touching commits; --lines scopes to a method or block.
10. Synthesize and render — emit a markdown report + structured JSON sidecar, then render_report.py produces a single self-contained HTML file (every PR / commit / ticket / file / chat thread is a clickable link).

---

What you get

A single, offline-renderable HTML file with:

• A chronological "Significant changes" feed down a vertical timeline. Notable commits expand into full cards (commit-head + diff snippet + the why); discussion items (PR reviews, Slack threads, ticket descriptions) interleave as cards in their place; smaller context moments render as 75%-width mini cards. Each card carries a colored 3px left strip — green for additions / discussion, red for changes / removals, gray for context.
• A "Risks & gotchas" panel of cards synthesizing the historical signal into actionable warnings: contracts that must hold, files that change in lockstep, known gotchas grounded in specific PRs / threads / tickets.
• Collapsed-by-default Frequent authors, Used by (structural callers), and Co-changes with this (temporal coupling) panels for the people and dependencies behind the code.
• A commit-cadence histogram of touching commits per month.
• Person chips in the prose: any mentioned author whose handle/email the skill knows gets a gravatar + linked name inline.
• GitHub-flavored markdown rendering with syntax-highlighted code (highlight.js + GitHub themes, light/dark adaptive), an auto-built ToC sidebar, and a one-click "Copy markdown" button so the report content drops cleanly into a comment or doc.

---

When it triggers

• Explicit: type /why.
• Auto-trigger on questions: "why does this code exist", "what's the history of X", "who wrote this and why", "what's the context here".
• Auto-trigger before risky edits: Claude reaches for it on its own when about to modify code that's unfamiliar, legacy, fragile, or whose intent is unclear — the kind of change that silently regresses hard-won fixes if you skip the history check.
• During code review: when reading someone else's change and needing the context they had.
• Anti-trigger: not for runtime debugging ("why is my test failing"). Use a debugger for that. why is for archaeology, not introspection.

---

How to use it