The Archaeologist’s Field Notes

“History doesn’t repeat itself, but it rhymes. Static analysis tells you 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: a system’s evolution history** reveals design problems better than the code alone.

⚠️ Mandatory Deep Thinking

[!IMPORTANT]
Before performing any analysis, you must invoke the mcpsequential-thinkingsequentialthinking tool and reason for 3–10 steps, or more if needed.

Example thinking prompts:

1. “How deep is this project’s Git history? Do I need git fetch --unshallow?”
2. “Which time window should I focus on? (Last 3 months? 1 year?)”
3. “Are there obvious noise files (e.g. package-lock.json) that must be excluded?”

⚡ Quick Start

1. Coupling analysis

``bash python scripts/git_forensics.py --repo . --threshold 0.3 ``

1. Hotspot detection

``bash python scripts/git_hotspots.py --repo . --days 180 ``

🧭 Exploration Process (The Dig)

Step 1: Sense the Flow of Time (The Tornhill Method)

• Master’s saying:

“The value of code is not what it is, but how it became that way.”

• Run:

``bash git log --oneline -n 100 ``

to quickly gauge recent project activity.

• Key inference:

If the last ~50 commits touch only one or two directories, that’s the epicenter—the area most likely hiding risk.

Step 2: Discover Hidden Coupling

(Temporal Coupling / Change Coupling)

• Core question:

“Are there two files that have no import/use relationship, yet appear together in 70% of commits?”

• Master warnings (from Adam Tornhill):

⚠️ Logical coupling with physical separation → strong signal of architectural decay ⚠️ Cross–build-root coupling → if service/ipc.rs and gui/api.ts change together but belong to different build roots, this is a breeding ground for version skew * Prescription:

Either merge them into the same module, or Extract a shared schema / contract layer

Step 3: Identify Hotspots

(CodeScene Methodology)

• Formula:

Hotspot = High Change Frequency (Churn) × High Complexity

• Master strategy matrix (from CodeScene):

• Master advice:

With limited refactoring capacity, only attack the High-Churn + High-Complexity quadrant. That’s where ROI is highest.

🛡️ Master Rules

1. Unshallow first:

Run git fetch --unshallow. No history = no data = blind analysis.

1. Filter noise:

Exclude package-lock.json, Cargo.lock, *.min.js, dist/, and other generated artifacts—they pollute results.

1. Beware mass renames:

git mv can distort coupling signals. If results look strange, manually verify rename history.

1. Link to build topology:

When reporting coupled file pairs, annotate their respective build roots. This is the critical bridge between Git forensics and build analysis.

📤 Required Output

Your report must include:

1. Coupling Pairs

File pairs with coupling score > 0.7, annotated with their build roots

1. Cross-Root Couplings

Highlight explicitly — if two highly coupled files belong to different build roots, this is the #1 risk

1. Hotspots

List of high-risk modules (high churn + high complexity)

1. Orphans

Files untouched for over 1 year (knowledge-decay warning)

1. Refactoring Priority

Suggested refactor order based on the churn/complexity matrix