Fossil Record

Fossil Record

"Code tells you what a system does. History tells you what a system survived."

What It Does

git blame tells you WHO changed a line. git log tells you WHEN. Fossil Record tells you WHY — by analyzing patterns across the entire commit history to reconstruct the evolutionary pressures that shaped the codebase.

Every line of code is the result of a decision. Most decisions aren't documented. But they leave fossils: commit patterns, revert sequences, hotfix clusters, refactor waves, and the sediment of a hundred small choices that accumulated into the architecture you see today.

The Geological Model

Fossil Record treats your git history as a geological record, with distinct layers and eras:

The Eight Excavation Modes

1. Pressure Analysis

Question: What external forces shaped this code?

Analyzes commit message patterns, timing, and clustering to identify:

• Deadline pressure: Commits accelerating toward a date, then stopping
• Incident pressure: Hotfix → fix → fix-the-fix → revert → different-fix patterns
• Stakeholder pressure: Feature requests appearing as interruptive commit sequences
• Technical debt pressure: Refactors that are started, abandoned, restarted

Output: Timeline of external pressures with their impact on code quality.
Example: "Between March 3-17, commit velocity tripled and test coverage
dropped from 84% to 61%. Three hotfixes followed in the next week.
This region of code still carries the scars of that deadline."

2. Decision Reconstruction

Question: What decisions were made here, and what alternatives were considered?

Analyzes:

• Reverted commits (something was tried and rejected)
• Branches that were created but never merged (abandoned approaches)
• Comments that reference alternatives ("we could have used X but...")
• Sequential implementations of the same feature (iteration history)

Output: Decision tree showing what was tried, what stuck, and what was abandoned.
Example: "Authentication was implemented 3 times:
  v1 (session-based, commits a1b2..c3d4, reverted)
  v2 (JWT, commits e5f6..g7h8, lived 4 months)
  v3 (OAuth2, commits i9j0..k1l2, current)
  Pressure: v1→v2 driven by scaling issues. v2→v3 driven by SSO requirement."

3. Hotspot Archaeology

Question: Why is this specific area of code so volatile?

Goes beyond "this file changes often" to ask "what kind of changes happen here and what drives them?"

CHANGE TAXONOMY:
├── Bug Fix: Same function modified to fix different bugs (fragile design)
├── Feature Accretion: Function grows as features are bolted on (missing abstraction)
├── Config Churn: Constants/thresholds repeatedly adjusted (unclear requirements)
├── Refactor Oscillation: Code restructured back and forth (no consensus on design)
└── Dependency Turbulence: Changes driven by upstream library updates (fragile coupling)

4. Extinction Mapping

Question: What used to be here, and why did it die?

Traces deleted code through git history to reconstruct what was removed and the conditions of its removal:

• Was it replaced? By what?
• Was it gradually abandoned or suddenly deleted?
• Did its removal cause any subsequent issues (fixes referencing the deleted module)?
• Is anything still alive that was designed to work with the extinct module?

Output: Extinction timeline showing what disappeared, when, and what it left behind.
Example: "The 'recommendations' module was deleted in commit x1y2z3 (June 2024).
  3 orphaned database tables still exist.
  2 API routes still reference recommendation types in their schemas.
  1 test file still imports a mock of the recommendation engine."

5. Sediment Dating

Question: How old is this code really, and has it been maintained or just preserved?

For each module/file, determines:

• Birth date: When was it first created?
• Last meaningful change: Not just whitespace/formatting — actual behavior change
• Maintenance frequency: Is it regularly updated or untouched?
• Author diversity: Has only one person ever modified this? (bus factor = 1)
• Era classification: Which architectural era does this code belong to?

Output: Age map of the codebase with era boundaries.
Example:
  src/auth/     Born: 2023-01, Last modified: 2025-11, Era: "Current" (3rd gen)
  src/utils/    Born: 2021-06, Last modified: 2022-03, Era: "Founding" (1st gen)
  src/payments/ Born: 2024-08, Last modified: 2024-08, Era: "Growth" (2nd gen)
  ⚠️ src/utils/ hasn't been meaningfully modified in 3 years. Fossil bed.

6. Fault Line Detection

Question: Where are the tectonic boundaries in this codebase?

Identifies major architectural shifts by finding:

• Large-scale rename/move operations
• Dependency replacements (library A → library B)
• Directory restructuring
• Changes to build systems, frameworks, or deployment targets

Output: Fault line map showing architectural eras and their boundaries.
Example: "3 major fault lines detected:
  1. [2022-09] Monolith → microservices split (142 files moved)
  2. [2023-06] REST → GraphQL migration (89 files modified)
  3. [2024-03] JavaScript → TypeScript conversion (204 files renamed)
  Warning: Fault line #2 is incomplete. 23 endpoints still REST."

7. Author Topology

Question: How was knowledge distributed, and where are the gaps?

Maps which developers contributed to which areas, and identifies:

• Knowledge monopolies: Areas only one person has ever touched
• Knowledge transfers: When a new contributor takes over an area
• Knowledge voids: When all contributors to an area have left the project
• Collaboration patterns: Which areas have healthy multi-author contribution

Output: Knowledge topology map with risk assessment.
Example: "src/billing/ — ALL 247 commits by developer X (last active: 2024-01).
  Developer X is no longer on the team.
  No other contributor has ever modified this module.
  Knowledge void. Recommend: dedicated onboarding session for this module."

8. Evolution Trajectory

Question: Where is this codebase heading?

Extrapolates from historical patterns to predict:

• Which areas are actively evolving (increasing commit diversity and frequency)
• Which areas are calcifying (decreasing modifications, aging contributors)
• Which architectural patterns are expanding vs. contracting
• What the next likely "extinction event" or "fault line" might be

Output: Trajectory forecast based on historical momentum.
Example: "The codebase is trending toward:
  ✓ Full TypeScript adoption (92% converted, ~2 months to completion)
  ✓ GraphQL as primary API layer (78% migrated)
  ⚠ Growing divergence between /api and /services naming conventions
  ⚠ Test coverage declining in modules > 2 years old (neglect pattern)"

Integration

Invoke Fossil Record when:
├── Joining a new project      → Run full geological survey
├── Before modifying old code  → Run sediment dating + decision reconstruction
├── After an incident          → Run pressure analysis on the affected area
├── During architecture review → Run fault line detection + evolution trajectory
├── When someone asks "why?"   → Run decision reconstruction on that specific area
└── Onboarding new developers  → Generate the complete evolutionary narrative

Output: The Geological Survey

╔══════════════════════════════════════════════════════════════╗
║                 FOSSIL RECORD: GEOLOGICAL SURVEY            ║
║                 Repository: acme-platform                   ║
║                 History depth: 3 years, 4,721 commits       ║
╠══════════════════════════════════════════════════════════════╣
║                                                              ║
║  ERAS IDENTIFIED: 3                                          ║
║  ├── Founding (2022-01 → 2022-09): Monolith, Express, JS    ║
║  ├── Growth (2022-09 → 2024-03): Microservices, REST, JS/TS ║
║  └── Current (2024-03 → now): Microservices, GraphQL, TS    ║
║                                                              ║
║  FAULT LINES: 3 major, 7 minor                              ║
║  IMPACT CRATERS: 12 incidents (3 P0, 5 P1, 4 P2)           ║
║  FOSSIL BEDS: 4 modules unchanged > 18 months               ║
║  KNOWLEDGE VOIDS: 2 modules (all authors departed)          ║
║  EXTINCTION EVENTS: 8 modules deleted, 3 left artifacts     ║
║                                                              ║
║  TRAJECTORY: Healthy evolution with 2 risk areas             ║
╚══════════════════════════════════════════════════════════════╝

Why It Matters

Code review looks at the present. Testing validates the expected. Fossil Record illuminates the past — because a codebase that doesn't understand its own history is condemned to repeat its own mistakes.

Zero external dependencies. Pure git analysis. No APIs, no cloud, no cost.