git-forensics

The Archaeologist's Field Notes

"History doesn't repeat itself, but it rhymes. Static analysis tells you the structure, Git forensics tells you the painful truth." — Adam Tornhill

This skill is based on Adam Tornhill's "Your Code as a Crime Scene" methodology. Core idea: the code'sevolution historyreveals design problems better than the code itself.

---

⚠️ Mandatory deep thinking

[!IMPORTANT] Before performing any analysis, youmustcall the sequential thinking tool, and as appropriate perform 2—3 stepsof reasoning. Examples of what to think about:

1. "How deep is this project's Git history? Is it necessary to git fetch --unshallow？"
2. "Which time range should I focus on? (Last 3 months? 1 year?)"
3. "Are there obvious 'noise files' (such as package-lock.json) that need to be excluded?"

---

⚡ Quick Start

1. Coupling analysis: python scripts/git_forensics.py --repo . --threshold 0.3
2. Hotspot detection: python scripts/git_hotspots.py --repo . --days 180

---

🧭 Exploration process (The Dig)

Step 1: Sense the flow of time (The Tornhill Method)

• Old master's words: "The value of code is not what it is, but how it became this way."
• Run git log --oneline -n 100to quickly sense the project's recent activity level.
• Key inference: If the last 50 commits all involve only one or two directories, that is the "epicenter"—the place most likely to hide risk.

Step 2: Discover hidden coupling (Temporal Coupling / Change Coupling)

• Core question: "Are there two files that, in the code,have no import/use relationship, but 70% commits always appear together?"
• Old master's alarm (from Adam Tornhill):
  • ⚠️ Logically coupled but physically separated -> This is a strong signal of "Architectural Decay"!
  • ⚠️ Coupling across build roots -> If service/ipc.rs always changes together with gui/api.ts , but they belong to different build roots, this is a breeding ground forversion drift!
  • Prescription: Either merge them into the same module, or abstract out a shared Schema/Contract layer.

Step 3: Locate hotspots (Hotspot Analysis - CodeScene Methodology)

• Formula: Hotspot = High change frequency (Churn) × High complexity (Complexity)

• Old master's strategy matrix (from CodeScene):

  	Low complexity	High complexity
  High Churn	Configuration/generated code, can be ignored	🔴 Refactor first! A breeding ground for bugs, highest ROI
  Low Churn	Stable module, don't touch	🟡 Legacy minefield, tread carefully

• Old master's advice: When refactoring resources are limited,Focus only on the quadrant with high Churn + high Complexity. This is where the return on investment is highest.

---

🛡️ Old Master's Rules

1. First, cancel shallow clone: git fetch --unshallow. No history = no data = you are blind.
2. Filter out noise: Ignore package-lock.json, Cargo.lock, *.min.js, dist/ and other generated artifacts. They will pollute your analysis results.
3. Be wary of large-scale renames: Renames (git mv) can interfere with tracking. If you find strange coupling data, manually check whether it was caused by a rename.
4. Associate build information: When outputting coupling pairs,annotate which build root each of them belongs to. This is the key bridge connecting Git analysis and Build analysis.

---

📤 Output Checklist

1. Coupling Pairs: File pairs with Score > 0.7.Annotate their build roots。
2. Cross-Root Couplings: Highlight these! If two highly coupled files belong to different build roots, this is anumber one risk。
3. Hotspots: List of high-risk modules (high Churn + high Complexity).
4. Orphans: Files untouched for more than 1 year (knowledge rot warning).
5. Refactoring Priority: Based on the Churn/Complexity matrix, give recommended refactoring priorities.