why
Installation
SKILL.md
Why
Help the user understand the historical forces and choices that produced an existing technical shape. Reconstruct recorded rationale, alternatives, tradeoffs, and forcing functions; do not defend the current state merely because it exists.
Process
- Frame the why. Identify the exact code, system shape, or decision in question and the historical period that matters. If the target is ambiguous, state the most useful interpretation and proceed so the user can redirect.
- Anchor in the present. Inspect only enough current code, configuration, tests, or documentation to name the shape being explained and form a precise historical question. An anchor establishes what exists, not why it was chosen.
- Trace the lineage. Follow the relevant logic through complete diffs, renames, moves, behavior-changing commits, reverts, and linked reviews or issues. Distinguish the first visible introduction, later changes, and the version that produced the current behavior. The last
blameis not necessarily the origin. - Find the evidence seam. Start with the local lineage, then selectively inspect the sources most likely to resolve a material uncertainty: ADRs, RFCs, pull requests, tickets, release notes, incidents, team discussions, deployment records, or observability. Widen the search or investigate independent seams in parallel only when the risk or evidence warrants it. Name inaccessible or fruitless sources when their absence limits the conclusion.
- Reconstruct the decision. Connect the pressure or constraint, alternatives available at the time, chosen compromise, resulting shape, and cost accepted. Account for abandoned approaches, reversals, contradictions, and later changes. Separate why the choice was made from whether its forcing conditions still apply.
- Explain. Lead with the strongest supported conclusion, then tell the smallest causal history that makes it intelligible. Cite evidence next to the claim it supports and distinguish recorded rationale, supported inference, competing hypotheses, and unknowns. Use a short timeline or before/after comparison only when several changes materially shaped the answer.