{"skill":{"slug":"fossil-record","displayName":"Fossil Record","summary":"Git archaeology engine that reconstructs the WHY behind code — not what changed, but what pressures, failures, and pivots shaped the codebase into its curren...","description":"---\nname: fossil-record\nversion: 1.0.0\ndescription: >\n  Git archaeology engine that reconstructs the WHY behind code — not what\n  changed, but what pressures, failures, and pivots shaped the codebase into\n  its current form. Reads commit history the way a paleontologist reads\n  sediment layers: to understand the forces that created the present.\nauthor: J. DeVere Cooley\ncategory: code-archaeology\ntags:\n  - git-analysis\n  - code-history\n  - decision-reconstruction\n  - archaeology\nmetadata:\n  openclaw:\n    emoji: \"🦴\"\n    os: [\"darwin\", \"linux\", \"win32\"]\n    cost: free\n    requires_api: false\n    tags:\n      - zero-dependency\n      - cognitive\n      - history\n---\n\n# Fossil Record\n\n> \"Code tells you what a system does. History tells you what a system *survived*.\"\n\n## What It Does\n\n`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.\n\nEvery 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.\n\n## The Geological Model\n\nFossil Record treats your git history as a geological record, with distinct layers and eras:\n\n| Geological Concept | Code Equivalent |\n|---|---|\n| **Sediment Layers** | Periods of steady development (feature commits) |\n| **Fault Lines** | Major refactors, rewrites, or architecture changes |\n| **Impact Craters** | Incident responses, emergency hotfixes, reverts |\n| **Fossil Beds** | Code that hasn't changed in a long time (stable or forgotten?) |\n| **Erosion Patterns** | Gradual drift from original design intent |\n| **Extinction Events** | Deleted modules, abandoned features, removed dependencies |\n| **Adaptive Radiation** | Rapid diversification after a major change (new abstraction spawning many implementations) |\n\n## The Eight Excavation Modes\n\n### 1. Pressure Analysis\n**Question:** What external forces shaped this code?\n\nAnalyzes commit message patterns, timing, and clustering to identify:\n- **Deadline pressure**: Commits accelerating toward a date, then stopping\n- **Incident pressure**: Hotfix → fix → fix-the-fix → revert → different-fix patterns\n- **Stakeholder pressure**: Feature requests appearing as interruptive commit sequences\n- **Technical debt pressure**: Refactors that are started, abandoned, restarted\n\n```\nOutput: Timeline of external pressures with their impact on code quality.\nExample: \"Between March 3-17, commit velocity tripled and test coverage\ndropped from 84% to 61%. Three hotfixes followed in the next week.\nThis region of code still carries the scars of that deadline.\"\n```\n\n### 2. Decision Reconstruction\n**Question:** What decisions were made here, and what alternatives were considered?\n\nAnalyzes:\n- Reverted commits (something was tried and rejected)\n- Branches that were created but never merged (abandoned approaches)\n- Comments that reference alternatives (\"we could have used X but...\")\n- Sequential implementations of the same feature (iteration history)\n\n```\nOutput: Decision tree showing what was tried, what stuck, and what was abandoned.\nExample: \"Authentication was implemented 3 times:\n  v1 (session-based, commits a1b2..c3d4, reverted)\n  v2 (JWT, commits e5f6..g7h8, lived 4 months)\n  v3 (OAuth2, commits i9j0..k1l2, current)\n  Pressure: v1→v2 driven by scaling issues. v2→v3 driven by SSO requirement.\"\n```\n\n### 3. Hotspot Archaeology\n**Question:** Why is this specific area of code so volatile?\n\nGoes beyond \"this file changes often\" to ask \"what *kind* of changes happen here and what drives them?\"\n\n```\nCHANGE TAXONOMY:\n├── Bug Fix: Same function modified to fix different bugs (fragile design)\n├── Feature Accretion: Function grows as features are bolted on (missing abstraction)\n├── Config Churn: Constants/thresholds repeatedly adjusted (unclear requirements)\n├── Refactor Oscillation: Code restructured back and forth (no consensus on design)\n└── Dependency Turbulence: Changes driven by upstream library updates (fragile coupling)\n```\n\n### 4. Extinction Mapping\n**Question:** What used to be here, and why did it die?\n\nTraces deleted code through git history to reconstruct what was removed and the conditions of its removal:\n- Was it replaced? By what?\n- Was it gradually abandoned or suddenly deleted?\n- Did its removal cause any subsequent issues (fixes referencing the deleted module)?\n- Is anything still alive that was designed to work with the extinct module?\n\n```\nOutput: Extinction timeline showing what disappeared, when, and what it left behind.\nExample: \"The 'recommendations' module was deleted in commit x1y2z3 (June 2024).\n  3 orphaned database tables still exist.\n  2 API routes still reference recommendation types in their schemas.\n  1 test file still imports a mock of the recommendation engine.\"\n```\n\n### 5. Sediment Dating\n**Question:** How old is this code *really*, and has it been maintained or just preserved?\n\nFor each module/file, determines:\n- **Birth date**: When was it first created?\n- **Last meaningful change**: Not just whitespace/formatting — actual behavior change\n- **Maintenance frequency**: Is it regularly updated or untouched?\n- **Author diversity**: Has only one person ever modified this? (bus factor = 1)\n- **Era classification**: Which architectural era does this code belong to?\n\n```\nOutput: Age map of the codebase with era boundaries.\nExample:\n  src/auth/     Born: 2023-01, Last modified: 2025-11, Era: \"Current\" (3rd gen)\n  src/utils/    Born: 2021-06, Last modified: 2022-03, Era: \"Founding\" (1st gen)\n  src/payments/ Born: 2024-08, Last modified: 2024-08, Era: \"Growth\" (2nd gen)\n  ⚠️ src/utils/ hasn't been meaningfully modified in 3 years. Fossil bed.\n```\n\n### 6. Fault Line Detection\n**Question:** Where are the tectonic boundaries in this codebase?\n\nIdentifies major architectural shifts by finding:\n- Large-scale rename/move operations\n- Dependency replacements (library A → library B)\n- Directory restructuring\n- Changes to build systems, frameworks, or deployment targets\n\n```\nOutput: Fault line map showing architectural eras and their boundaries.\nExample: \"3 major fault lines detected:\n  1. [2022-09] Monolith → microservices split (142 files moved)\n  2. [2023-06] REST → GraphQL migration (89 files modified)\n  3. [2024-03] JavaScript → TypeScript conversion (204 files renamed)\n  Warning: Fault line #2 is incomplete. 23 endpoints still REST.\"\n```\n\n### 7. Author Topology\n**Question:** How was knowledge distributed, and where are the gaps?\n\nMaps which developers contributed to which areas, and identifies:\n- **Knowledge monopolies**: Areas only one person has ever touched\n- **Knowledge transfers**: When a new contributor takes over an area\n- **Knowledge voids**: When all contributors to an area have left the project\n- **Collaboration patterns**: Which areas have healthy multi-author contribution\n\n```\nOutput: Knowledge topology map with risk assessment.\nExample: \"src/billing/ — ALL 247 commits by developer X (last active: 2024-01).\n  Developer X is no longer on the team.\n  No other contributor has ever modified this module.\n  Knowledge void. Recommend: dedicated onboarding session for this module.\"\n```\n\n### 8. Evolution Trajectory\n**Question:** Where is this codebase *heading*?\n\nExtrapolates from historical patterns to predict:\n- Which areas are actively evolving (increasing commit diversity and frequency)\n- Which areas are calcifying (decreasing modifications, aging contributors)\n- Which architectural patterns are expanding vs. contracting\n- What the next likely \"extinction event\" or \"fault line\" might be\n\n```\nOutput: Trajectory forecast based on historical momentum.\nExample: \"The codebase is trending toward:\n  ✓ Full TypeScript adoption (92% converted, ~2 months to completion)\n  ✓ GraphQL as primary API layer (78% migrated)\n  ⚠ Growing divergence between /api and /services naming conventions\n  ⚠ Test coverage declining in modules > 2 years old (neglect pattern)\"\n```\n\n## Integration\n\n```\nInvoke Fossil Record when:\n├── Joining a new project      → Run full geological survey\n├── Before modifying old code  → Run sediment dating + decision reconstruction\n├── After an incident          → Run pressure analysis on the affected area\n├── During architecture review → Run fault line detection + evolution trajectory\n├── When someone asks \"why?\"   → Run decision reconstruction on that specific area\n└── Onboarding new developers  → Generate the complete evolutionary narrative\n```\n\n## Output: The Geological Survey\n\n```\n╔══════════════════════════════════════════════════════════════╗\n║                 FOSSIL RECORD: GEOLOGICAL SURVEY            ║\n║                 Repository: acme-platform                   ║\n║                 History depth: 3 years, 4,721 commits       ║\n╠══════════════════════════════════════════════════════════════╣\n║                                                              ║\n║  ERAS IDENTIFIED: 3                                          ║\n║  ├── Founding (2022-01 → 2022-09): Monolith, Express, JS    ║\n║  ├── Growth (2022-09 → 2024-03): Microservices, REST, JS/TS ║\n║  └── Current (2024-03 → now): Microservices, GraphQL, TS    ║\n║                                                              ║\n║  FAULT LINES: 3 major, 7 minor                              ║\n║  IMPACT CRATERS: 12 incidents (3 P0, 5 P1, 4 P2)           ║\n║  FOSSIL BEDS: 4 modules unchanged > 18 months               ║\n║  KNOWLEDGE VOIDS: 2 modules (all authors departed)          ║\n║  EXTINCTION EVENTS: 8 modules deleted, 3 left artifacts     ║\n║                                                              ║\n║  TRAJECTORY: Healthy evolution with 2 risk areas             ║\n╚══════════════════════════════════════════════════════════════╝\n```\n\n## Why It Matters\n\nCode 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.\n\nZero external dependencies. Pure git analysis. No APIs, no cloud, no cost.\n","tags":{"latest":"1.0.0"},"stats":{"comments":0,"downloads":529,"installsAllTime":2,"installsCurrent":2,"stars":0,"versions":1},"createdAt":1772568135149,"updatedAt":1778491707669},"latestVersion":{"version":"1.0.0","createdAt":1772568135149,"changelog":"Initial release — Git archaeology engine that reconstructs the WHY behind code","license":null},"metadata":{"setup":[],"os":["darwin","linux","win32"],"systems":null},"owner":{"handle":"jcools1977","userId":"s17ebw5h443w8hw0qvntmyrad1884ra1","displayName":"John DeVere Cooley","image":"https://avatars.githubusercontent.com/u/75928463?v=4"},"moderation":null}