Code Archaeology (git + in-repo)

Source

This page reprints the English original.

pstack/skills/why/references/sources/code-archaeology.md (cursor/plugins 12d587d).

中文页

Code Archaeology (git + in-repo)

What this source contains

• Commit history (messages, dates, authors, diffs)
• PR descriptions, review comments, and discussion threads (via gh)
• Inline code comments, TODOs, FIXMEs, deprecation notes
• ADRs (architectural decision records) if the repo keeps them
• Tests. Names and assertions often encode the edge cases that motivated a change
• Related files modified in the same commits (co-change signal)
• CHANGELOG entries, release notes in the repo
• Issue/ticket IDs mentioned in commit messages and PR bodies

The most trustworthy source, tied directly to the code, and the most complete. Everything that went through the repo should be here.

How to search it

Expand the seed commit list:

# Full history of the file through renames
git log --follow --oneline -- <file>

# Pickaxe: commits that added or removed this exact text
git log -S '<exact_string_from_code>' -- <file>

# Or for patterns:
git log -G '<regex>' -- <file>

# Who wrote each line and when
git blame -L <start>,<end> <file>

# The full diff of a specific commit
git show <hash>

# Commits between two points affecting this file
git log <old>..<new> -p -- <file>

For each substantive commit, pull the PR context:

# Find the PR number from the merge commit or branch
git log -1 --format=%B <hash>

# Full PR context: body, review comments, linked issues
gh pr view <number> --json title,body,author,createdAt,mergedAt,labels,closingIssuesReferences,comments,reviews,files

# The --json reviews and comments fields are where the real signal is

Look for out-of-band docs:

# ADRs often live in docs/adr/ or similar
rg -l -i 'architecture.decision' --glob '*.md'

# TODOs and FIXMEs near the target
rg -n -C2 '(TODO|FIXME|HACK|XXX|NOTE)' <target_file>

# Related tests. Names often encode the "why"
rg -l '<symbol>' --glob '*test*'

What good evidence looks like here

• A PR description that explains the problem being solved, not just the change (“This fixes the pagination bug that caused X”)
• A long review thread where alternatives were debated
• An inline comment near the target line that explains a non-obvious constraint
• A test named test_handles_edge_case_when_X that reveals an edge case motivating the code
• A commit message that references a ticket or incident ID
• A CHANGELOG entry that summarizes the user-visible rationale

Common pitfalls

• Squash-merge flatlands. If the repo squashes PRs, individual commits in the branch history are lost. Fall back to PR body and comments.
• Misleading commit messages. “Small refactor” sometimes hides an intentional behavior change. Look at the diff, not the message.
• Cargo-culted patterns. The author may have copied a pattern without understanding why. Check if the pattern originated earlier in the codebase and investigate that commit.
• Bot commits and auto-merges. Dependabot, Renovate, and automated backports usually don’t carry motivation. Skip them when trying to find intent.
• Treating code as evidence of intent. The code itself isn’t evidence for why it exists. Evidence comes from commit messages, PRs, comments, tests, docs. Don’t cite “the function is named X” as evidence of intent.

What to return

Every commit/PR/comment that bears on the question, with:

• The exact text (quoted)
• The hash / PR number / file:line
• Author and date
• Whether it’s direct (explicitly addresses the question) or circumstantial