Project Archaeology

You've got an existing project with months or years of history. Can you build a decision graph retroactively? Absolutely—and it's one of the most valuable things you can do.

The Scenario

Picture this: You're joining a project that's been running for two years. There's code everywhere, scattered documentation, and that one engineer who knew everything just left. The codebase works, but why does it work this way?

Or maybe it's your own project. You built it six months ago. You made decisions. But now you look at the code and think: "Why did I use MongoDB here? Was there a reason?"

This is where archaeology comes in—building a decision graph by mining your existing history.

The One Root Approach

Unlike forward logging where you create many independent goals, archaeology typically flows from one origin point because you're reconstructing a single project's history.

            ┌─────────────────────┐
            │   Project Origin    │   Root goal
            │  "Build Acme Corp"  │
            └──────────┬──────────┘
                       │
      ┌────────────────┼────────────────┐
      ▼                ▼                ▼
┌───────────┐   ┌───────────┐   ┌───────────┐
│   Auth    │   │ Database  │   │   API     │   Major themes
│  System   │   │  Choice   │   │  Design   │
└─────┬─────┘   └─────┬─────┘   └─────┬─────┘
      │               │               │
┌─────┴─────┐   ┌─────┴─────┐   ┌─────┴─────┐
│  Options  │   │  Options  │   │  Options  │   Branches of
│  Actions  │   │  Actions  │   │  Actions  │   exploration
│  Outcomes │   │  Outcomes │   │  Outcomes │
└───────────┘   └───────────┘   └───────────┘

Step 1: Initialize and Set the Root

Watch how we establish the foundation for reconstructing a project's decision history:

Step 2: Mine the Git Log for Major Themes

Your git history is a goldmine. Watch how we extract patterns:

From this mining, we can identify major themes:

• Authentication — JWT tokens, OAuth2 overhaul
• Database — PostgreSQL, MongoDB migration
• Integrations — ERP sync, webhooks
• Architecture — Multi-tenancy, realtime, GraphQL

Step 3: Create Decision Points for Major Themes

Now we translate those themes into decision nodes:

Step 4: Mine Issues and PRs for Context

GitHub issues and PRs often contain the why that's missing from commits:

Step 5: Trace Evolutionary Patterns

Projects evolve. Look for patterns where early decisions were revisited:

The Archaeology Checklist

A systematic approach to mining your project history:

A Real Example: Deciduous Itself

Watch archaeology in action on the deciduous project:

When to Do Archaeology

• Onboarding — New team member needs to understand why things are the way they are
• Major refactors — Before changing something, understand why it exists
• Documentation sprints — Convert tribal knowledge into queryable graph
• Post-mortems — Trace how decisions led to incidents
• Architecture reviews — See the full decision tree before adding more

Archaeology vs Forward Logging

Tips for Effective Archaeology

1. Start with major themes, not details. Don't try to capture every commit. Focus on the big decisions first.
2. Use commit hashes liberally. Link nodes to commits with --commit for traceability.
3. Backdate nodes to when decisions were made. Use --date "2023-06-15" to place nodes at their historical point in time. Supports YYYY-MM-DD, YYYY-MM-DD HH:MM:SS, and RFC3339 formats.
4. Capture uncertainty. If you're not sure why something was done, say so: -c 50 for low confidence.
5. Interview people. If the original developers are available, ask them. Capture their answers as prompts.
6. Don't over-connect. Some decisions are independent. Not everything needs to link to everything.