| 1 | # Code Archaeology (git + in-repo) |
| 2 | |
| 3 | ## What this source contains |
| 4 | |
| 5 | - Commit history (messages, dates, authors, diffs) |
| 6 | - PR descriptions, review comments, and discussion threads (via `gh`) |
| 7 | - Inline code comments, TODOs, FIXMEs, deprecation notes |
| 8 | - ADRs (architectural decision records) if the repo keeps them |
| 9 | - Tests. Names and assertions often encode the edge cases that motivated a change |
| 10 | - Related files modified in the same commits (co-change signal) |
| 11 | - CHANGELOG entries, release notes in the repo |
| 12 | - Issue/ticket IDs mentioned in commit messages and PR bodies |
| 13 | |
| 14 | The most trustworthy source, tied directly to the code, and the most complete. Everything that went through the repo should be here. |
| 15 | |
| 16 | ## How to search it |
| 17 | |
| 18 | Expand the seed commit list: |
| 19 | |
| 20 | ```bash |
| 21 | # Full history of the file through renames |
| 22 | git log --follow --oneline |
| 23 | |
| 24 | # Pickaxe: commits that added or removed this exact text |
| 25 | git log -S '<exact_string_from_code> |
| 26 | |
| 27 | # Or for patterns: |
| 28 | git log -G '<regex> |
| 29 | |
| 30 | # Who wrote each line and when |
| 31 | git blame -L <star |
| 32 | |
| 33 | # The full diff of a specific commit |
| 34 | git show <hash> |
| 35 | |
| 36 | # Commits between two points affecting this file |
| 37 | git log <old> |
| 38 | ``` |
| 39 | |
| 40 | For each substantive commit, pull the PR context: |
| 41 | |
| 42 | ```bash |
| 43 | # Find the PR number from the merge commit or branch |
| 44 | git log -1 --format=%B |
| 45 | |
| 46 | # Full PR context: body, review comments, linked issues |
| 47 | gh pr view <numbe |
| 48 | |
| 49 | # The --json reviews and comments fields are where the real signal is |
| 50 | ``` |
| 51 | |
| 52 | Look for out-of-band docs: |
| 53 | |
| 54 | ```bash |
| 55 | # ADRs often live in docs/adr/ or similar |
| 56 | rg -l -i 'architecture.decision |
| 57 | |
| 58 | # TODOs and FIXMEs near the target |
| 59 | rg -n -C2 '(TODO|FIXME|HACK|XXX|NOTE) |
| 60 | |
| 61 | # Related tests. Names often encode the "why" |
| 62 | rg -l '<symbol>' |
| 63 | ``` |
| 64 | |
| 65 | ## What good evidence looks like here |
| 66 | |
| 67 | - A PR description that explains the problem being solved, not just the change ("This fixes the pagination bug that caused X") |
| 68 | - A long review thread where alternatives were debated |
| 69 | - An inline comment near the target line that explains a non-obvious constraint |
| 70 | - A test named `test_handles_edge_case_when_X` that reveals an edge case motivating the code |
| 71 | - A commit message that references a ticket or incident ID |
| 72 | - A CHANGELOG entry that summarizes the user-visible rationale |
| 73 | |
| 74 | ## Common pitfalls |
| 75 | |
| 76 | - **Squash-merge flatlands.** If the repo squashes PRs, individual commits in the branch history are lost. Fall back to PR body and comments. |
| 77 | - **Misleading commit messages.** "Small refactor" sometimes hides an intentional behavior change. Look at the diff, not the message. |
| 78 | - **Cargo-culted patterns.** The author may have copied a pattern without understanding why. Check if the pattern originated earlier in the codebase and investigate |
| 79 | - **Bot commits and auto-merges.** Dependabot, Renovate, and automated backports usually don't carry motivation. Skip them when trying to find intent. |
| 80 | - **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. |
| 81 | |
| 82 | ## What to return |
| 83 | |
| 84 | Every commit/PR/comment that bears on the question, with: |
| 85 | - The exact text (quoted) |
| 86 | - The hash / PR number / file:line |
| 87 | - Author and date |
| 88 | - Whether it's direct (explicitly addresses the question) or circumstantial |