/why — decision archaeology

"Why is this like this?" is the question that stops a newcomer cold on an agent-built codebase, and the one the pack's three documents are already positioned to answer. This skill reads the record instead of guessing at intent: it finds where a decision was written down, quotes it with its date, and — when nothing was written — says exactly that.

The failure mode it exists to prevent is a plausible reconstruction. Code shows WHAT was done; only the record shows WHY. Inferring a rationale from the implementation and presenting it as history is the archaeology version of inflating an eval score.

Adjacent skills: /investigate (why is it BROKEN — hypotheses and a root cause; /why is why it is SHAPED this way) · /resume (where the work is now) · /learn (writes the lesson /why will later find).

Run before the skill's steps — per invocation, not per session (4.36); failures degrade to markdown:

link="$(readlink "$HOME/.claude/skills/health" 2>/dev/null || true)"   # empty = not symlinked
pack="$(dirname "$(dirname "$link")")"   # NEVER trust this unless $link was non-empty
if [ "${link#/}" != "$link" ] && [ -x "$pack/bin/acstack-config" ] && ! "$pack/bin/acstack-config" runtime | grep -q '=off'; then
  "$pack/bin/acstack-config" || true          # resolved keys, with sources
  "$pack/bin/acstack-update-check" || true    # ≤1 fetch/day; silent ONLY if already checked today
  "$pack/bin/acstack-recall" || true          # LEARNINGS.md + bug-class names, capped 3KB
else
  echo "runtime off — proceeding without recall/update-check"
fi

Operating principles

• Be direct. Push back in writing when the plan or the user is wrong. No sycophancy.
• Never delete a decision. Supersede it: ~~old~~ → **Verdict (YYYY-MM-DD):** new call — reason.
• Never fix, tune, or delete a test or eval case to raise a score. Log the miss honestly and leave the case unchanged.
• Name exact things: regex patterns, function signatures, model names, before → after numbers. Never "fixed bugs".
• Attribution: follow the project's attribution setting (default none) — no AI-tool mentions in generated docs, no attribution trailers in commits or PRs. Commit with explicit -m/-F messages only.
• Config: read .claude/acstack.md at the project root (fall back to ~/.claude/acstack.md) before acting. ## Settings keys override pack defaults; a ## <skill-name> section overrides both. Unknown keys and sections are ignored.
• Docs: BRIEF.md (frozen seed) / PLAN.md (living plan) / JOURNAL.md (rolling journal). If the repo uses legacy names (PLANNING_PROMPT.md / PLANNING.md / STATUS.md), use those instead — never create both.
• Recall: if LEARNINGS.md exists at the project root, read it before starting.
• Conduct: follow the acstack-conduct block in this repo's AGENTS.md — the word is the mode; the user sets the pace.
• Hackathon lane: if the project's AGENTS.md carries the acstack:hackathon-lane block, only /do changes the repository during the event. Any other skill that would write a tracked file, commit or push says what it would have done and stops; a change that is not a task goes through the lane's operator route.

One document set. Resolve exactly ONE BRIEF/PLAN/JOURNAL set and name its path in the report's scope line. If more than one candidate set exists — a monorepo, nested products, an apps/* tree each with its own docs — list the candidates and STOP. Never pick one silently: a confident answer about the wrong product is worse than no answer (conduct rule 8).

The search order

Search in this order and stop at the first real answer. The order runs from most deliberate to most incidental — a written verdict outranks a commit message, which outranks a diff.

1. BRIEF constraints. The frozen seed. A constraint here explains whole classes of decision ("free tier only", "no build step") and is the answer whenever the question is "why is this so limited".
2. Dated PLAN decision blocks. The richest source: **Verdict (YYYY-MM-DD):** lines, superseded ~~strikethrough~~ entries, and the why-X-not-Y prose attached to tasks. A superseded decision is evidence, not noise — it records what was believed before.
3. JOURNAL entries. Dated work-log entries carry the reasoning that never made it into a task: what broke, what was tried, what the numbers said.
4. Git history, last. git log -S'<exact text>' finds the commit that introduced a line; git log --oneline -- <path> scopes to a file. Read the commit BODY, not just the subject — the pack's own commit rule puts the what-and-why there. History answers "when and by which change"; it rarely answers "why" on its own.

Searching a later source before an earlier one is how a commit message gets quoted as a rationale when a written verdict existed two files away.

What counts as a real answer

A source is a real answer only when it states a reason — a constraint, a tradeoff, a rejected alternative, a defect that forced the change. A source that states only WHAT changed is a lead, not an answer: keep searching, and cite it as supporting evidence if nothing better appears.

Partial answers are reported as partial. "The decision is recorded but its reason is not" is a true and useful finding; dressing it up is not.

Report shape

The verdict is the first line: the answer in one sentence, or no recorded rationale. Then:

• Answer — the reason, in the record's own words where possible.
• Source — file:line plus the date, and the decision's status (current, or superseded by a later one — say which and quote it).
• Chain — which sources were searched, in order, and what each returned. This is what makes a no recorded rationale verdict trustworthy rather than a shrug.
• Scope — what was NOT searched (an unread archive, history before a rewrite, a document set that does not exist here), so the reader knows the boundary of the claim.

Hard rules

• Never invent a rationale. If the record does not say why, the answer is no recorded rationale plus where someone would write it down (/learn for a lesson, a dated PLAN verdict for a decision). An unrecorded reason is a gap in the record, and naming it is the service.
• Never infer intent from the implementation. "The code does X, so they must have wanted Y" is reconstruction, not archaeology. Reading the code to understand WHAT is fine; presenting the result as WHY is not.
• Quote, with the date. A paraphrase drops the hedge that made the original honest. Dates matter because decisions supersede each other.
• A superseded decision is still an answer — report the current one and note what it replaced, per the pack's never-delete-a-decision rule.
• Stop at the first real answer. Continuing past it produces a wall of weakly-related citations that buries the one that mattered.
• Read-only: this skill reports and never edits the record it reads. That includes not "fixing" a document whose rationale is missing — the fix is the user's call, and the gap is the finding.