Codebase Archaeology

---
description: Reconstruct the decision trail behind any piece of code
allowed-tools: Bash(git *), Read, Grep, Glob
---

# Codebase Archaeology

Investigate the history of a file or function and produce a narrative explaining *why* the code is the way it is — not just *what* it does.

## Arguments

- `$ARGUMENTS` — the file path, or `file:function` to narrow the investigation to a specific function

## Steps

1. **Identify the target.** If `$ARGUMENTS` contains a colon, split it into file and function name. Otherwise treat the entire file as the target.
2. **Run git blame.** Execute `git blame --line-porcelain <file>` to get per-line authorship and commit hashes. If a function name was specified, narrow the blame to those lines.
3. **Extract unique commits.** Collect the distinct commit hashes from the blame output.
4. **Inspect each commit.** For each unique commit, run:
   - `git log -1 --format="%H %an %ad %s" <hash>` for the summary
   - `git log -1 --format="%b" <hash>` for the full body (often contains PR references, issue links, or rationale)
5. **Trace PR references.** Search commit messages for patterns like `#\d+`, `pull/\d+`, `Fixes #\d+`, or `Closes #\d+`. Note these references.
6. **Build a timeline.** Sort commits chronologically and identify:
   - The **original author** and when the code was first introduced
   - **Major rewrites** — commits that changed >50% of the lines
   - **Bug fix layers** — commits that patched specific lines, especially with "fix" or "bug" in the message
   - **Refactors** — commits that restructured without changing behavior
7. **Check for deleted context.** Run `git log --follow --diff-filter=M -- <file>` to find renames and moves that might have separated the code from its original context.
8. **Read surrounding code** for additional clues: comments, TODO notes, linked documentation.

## Output format

Produce a narrative report with the following sections:

### Origin Story
When was this code first written, by whom, and what was the motivation?

### Evolution Timeline
A chronological list of significant changes with dates, authors, and reasons.

### Key Decisions
What architectural or design decisions are embedded in this code? Why were they made (based on commit messages, PR descriptions, and comments)?

### Buried Context
Any important context that is no longer obvious from reading the code alone — removed comments, old PR discussions referenced in commits, or patterns that only make sense knowing the history.

### Risk Areas
Lines or patterns that have been changed repeatedly (churn), which often indicate fragile or misunderstood code.

## Rules

- Stick to facts from the git history — do not speculate beyond what the evidence shows.
- Quote commit messages and PR references directly when they explain a decision.
- If the git history is shallow (e.g., a squash-merged repo), note the limitation.
- If there is no meaningful history (file was added in a single commit), say so and focus on the code itself.