---
name: why
description:
  "Investigate the historical rationale and causal chain behind code, architecture, thresholds,
  wrappers, defensive logic, regressions, or product behavior. Use for design intent, 'why does this
  exist', 'why did this start happening', postmortems, and pre-change constraint discovery.
  Correlates current code with Git, PR, issue, session, Scratchpad, upstream, and read-only live
  evidence while separating direct evidence from inference. Use how for current mechanics."
argument-hint: "<file/symbol/commit/PR or question>"
disable-model-invocation: true
---

# Why

Explain rationale and causality, not just mechanics. Current code proves what exists; it rarely
proves why the decision was made. Remain read-only.

Route mechanics-only questions to `how`. For a mixed question, establish only enough mechanics to
identify the decision point before investigating rationale.

## Evidence ranks

Rank each material claim:

1. **Direct contemporaneous evidence:** ADR, proposal, issue, PR discussion, commit message,
   incident, or session statement that explicitly gives the reason at decision time.
2. **Corroboration:** diff and chronology, tests encoding the constraint, telemetry, customer
   reports, or version-matched upstream source supporting that reason.
3. **Later recollection:** newer handoff, Scratchpad note, comment, or transcript describing an
   older decision.
4. **Inference:** rationale reconstructed from code shape, constraints, timing, or common practice.
5. **Unknown:** available evidence does not distinguish plausible explanations.

Current behavior can prove impact and current source can prove mechanics; neither alone proves
historical intent. Search indexes are discovery aids—cite their underlying source.

## 1. Fix the question and anchor

State the exact behavior, file/symbol/line, commit or PR, time window, and repository/worktree. Run
`git worktree list --porcelain` to confirm which checkout the anchor lives in.

If several anchors remain plausible after one bounded search, use the harness's structured question
tool before choosing a materially different investigation.

## 2. Trace code and Git chronology

Start at the narrowest relevant lines or symbol. Use blame as a pointer, not proof; moves and
formatting can obscure the originating decision. Identify:

- precursor behavior;
- earliest relevant change;
- linked PR, issue, ADR, or incident;
- follow-up fixes, reverts, and consequences;
- present implementation and whether the original constraint still holds.

Inspect exact GitHub objects when they are part of the causal chain. A closed issue or PR does not
by itself prove that work merged or behavior changed.

## 3. Escalate only while rationale is unresolved

Use the smallest next source that can answer the remaining gap, in this order: linked ADRs, issues,
reviews, incidents, and tracked docs; then the relevant Scratchpad research, issue, milestone,
reference, or handoff, reconciled with current evidence; then `cass` for bounded session-history
discovery and exact transcript context; then `production-support` for runtime or production
causality; then version-matched local upstream source, and official upstream source or release notes
when that is not enough.

Let each routed skill own its current tool mechanics. Record meaningful null results and do not turn
missing direct evidence into a broad archive or web sweep.

Stop when direct evidence answers the question without material contradiction, or when the bounded
source ladder is exhausted and further search is unlikely to distinguish the remaining hypotheses.

## 4. Build the causal account

Separate:

- **Trigger:** problem, constraint, incident, upstream change, or product decision.
- **Decision:** chosen response and the record that states its rationale.
- **Implementation:** commits and files that enacted it.
- **Consequences:** intended effect, tradeoffs, regressions, and follow-ups.
- **Current validity:** original assumptions that still hold or have expired.

Classify alternatives as explicitly considered, explicitly rejected, later proposed, or plausible
but not evidenced. Never invent rejected alternatives.

## Answer shape

Return the smallest useful subset:

1. **Answer** — direct conclusion and confidence: high, medium, or low. Confidence is high with
   direct evidence plus corroboration and no material contradiction; medium with partial direct
   evidence or several independent corroborating sources; low when inference or missing primary
   evidence dominates.
2. **Causal timeline** — trigger, decision, implementation, and consequences with evidence rank.
3. **Direct evidence** — contemporaneous statements and their exact scope.
4. **Corroboration and inference** — clearly separated support and reconstruction.
5. **Unknowns and search boundary** — competing hypotheses, null results, and stopping reason.
6. **Current change constraints** — preserve/can-change/risk only when relevant to future work.

Finish when the causal claim and its confidence are supported, alternatives are honestly classified,
unknowns are visible, and further search is unlikely to change the answer. Do not implement a fix as
part of a `why` investigation.