Code Archaeology (git + in-repo)
Code Archaeology (git + in-repo)
Section titled “Code Archaeology (git + in-repo)”What this source contains
Section titled “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, whose names and assertions often encode the edge cases that motivated a change
- Related files modified in the same commits (co-change signal)
- CHANGELOG entries and release notes in the repo
- Issue/ticket IDs 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
Section titled “How to search it”Expand the seed commit list:
# History through renamesgit log --follow --oneline -- <file>
# Pickaxe: commits that added or removed this exact textgit log -S '<exact_string_from_code>' -- <file>
# Or for patterns:git log -G '<regex>' -- <file>
# Who wrote each line and whengit blame -L <start>,<end> <file>
# One commit's full diffgit show <hash>
# Commits between two points affecting this filegit log <old>..<new> -p -- <file>For each substantive commit, pull the PR context:
# PR number from the merge commit or branchgit log -1 --format=%B <hash>
# Body, review comments, linked issues. In a PR with discussion, reviews and comments hold the real signalgh pr view <number> --json title,body,author,createdAt,mergedAt,labels,closingIssuesReferences,comments,reviews,filesLook for out-of-band docs:
# ADRs often live in docs/adr/ or similarrg -l -i 'architecture.decision' --glob '*.md'
# TODOs and FIXMEs near the targetrg -n -C2 '(TODO|FIXME|HACK|XXX|NOTE)' <target_file>
# Related testsrg -l '<symbol>' --glob '*test*'What good evidence looks like here
Section titled “What good evidence looks like here”- A PR description that explains the problem, 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_Xthat reveals a motivating edge case - A commit message that references a ticket or incident ID
- A CHANGELOG entry that summarizes the user-visible rationale
Common pitfalls
Section titled “Common pitfalls”- Squash-merge flatlands. Squashed PRs lose their branch commits. Fall back to the 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 whether it originated earlier in the codebase, and investigate that commit.
- Bot commits and auto-merges. Dependabot, Renovate, and automated backports usually carry no motivation. Skip them when looking for intent.
- Treating code as evidence of intent. The code isn’t evidence for why it exists. Evidence comes from commit messages, PRs, comments, tests, and docs. Don’t cite “the function is named X” as evidence of intent.
What to return
Section titled “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
