Decision archaeology

Code tells you what. It almost never tells you why. The why was decided out loud, in a meeting, and then lost. This skill reconstructs it.

When to use this

• Someone asks why something is built the way it is
• A change looks obviously correct and you want to know what it breaks
• Onboarding: understanding the shape of a system
• A past decision is being re-litigated and nobody remembers the original reasoning

Do not use this to justify a decision after the fact. You are reconstructing what happened, not building a case.

Procedure

1. Fix the target precisely

Get the narrowest thing you can name: a file, a function, a config value, a dependency, a schema column. "Why is our auth like this" is too broad — narrow to src/auth/session.ts:refreshToken or SESSION_TTL=900.

2. Read the artifact itself first

Before searching anywhere else, read the code and its comments. A surprising share of "why" questions are answered by a comment three lines up that nobody read.

3. Walk the git history

git log -L :<function>:<file>          # history of one function
git log -S '<exact string>' --oneline  # commits that added/removed a value
git log --follow -p -- <file>          # full history including renames

For each candidate commit, read the full message body, not the subject. Then find the PR:

gh pr list --search "<commit sha>" --state all
gh pr view <number> --comments

PR review threads are where reasoning usually lives.

4. Search the meeting record

If a Wisprnote MCP server is connected, this is the highest-value step — it reaches conversations that were never written down:

• search_meetings with the feature name, the rejected alternative, and the error or constraint that forced the choice. Search all three; they surface different meetings.
• get_meeting on each hit, and read the decisions and transcription sections, not just the summary. Summaries compress away the reasoning.
• get_knowledge_graph or get_meeting_knowledge to find meetings linked to the same topic that your keyword search missed.

Without Wisprnote, substitute whatever written record exists: ADRs in docs/, RFCs, the issue tracker, design docs, Slack exports. Say which sources you searched.

5. Reconstruct and report

Write up what you found in this shape:

## <the thing>

**Decision:** <what was chosen, stated plainly>
**When:** <date> — <where it was decided>
**Decided by:** <names, if known>

**Why:** <the reasoning, in their words where you have them>

**Rejected alternatives:**
- <option> — rejected because <reason>

**Constraints at the time:** <what was true then that may not be true now>

**Evidence:**
- <commit / PR / meeting, each with an identifier someone can open>

**Confidence:** high | medium | low — <what is inferred vs. documented>

Guardrails

• Separate evidence from inference. If you are guessing, label it. "No record found; the commit message suggests X" is a useful answer. A confident fabrication is not.
• Say when you find nothing. An honest "no decision record exists for this" tells the reader they are free to change it — which is itself the answer they needed.
• Constraints expire. A decision that was right under a constraint that no longer holds is not binding. Always report the constraints alongside the decision.
• Never present a reconstruction as a direct quote unless you actually have the words.