archaeology

name	archaeology
description	Transform narratives into a queryable decision graph
compatibility	opencode

Archaeology

Transform narratives into a queryable decision graph.

Run /narratives first to create .deciduous/narratives.md.

Step 1: Read the narratives

deciduous narratives show

For each narrative, you'll create a subgraph.

Step 2: Create root goals

For each narrative, create a backdated goal:

deciduous add goal "<Narrative title>" -c 90 --date "YYYY-MM-DD"

Step 3: Build initial approaches

deciduous add decision "<First approach>" -c 85 --date "YYYY-MM-DD"
deciduous link <goal> <decision> -r "Initial design"

Step 4: Create pivots with archaeology pivot

For each PIVOT in a narrative, use the atomic pivot command:

deciduous archaeology pivot <from_id> "<what was learned>" "<new approach>" -c 85 -r "<why it failed>"

This automatically creates:

• observation node (what was learned)
• revisit node (reconsidering the old approach)
• decision node (the new approach)
• All 3 linking edges
• Marks the old approach as superseded

Preview before executing:

deciduous archaeology pivot <from_id> "observation" "new approach" --dry-run

Step 5: Connect narratives

When narratives reference each other:

deciduous link <auth_observation> <ratelimit_decision> \
  -r "Auth failures drove rate limit redesign"

Step 6: Mark superseded paths

For nodes that were replaced but not part of a pivot:

# Single node
deciduous archaeology supersede <id>

# Node and all descendants
deciduous archaeology supersede <id> --cascade

Step 7: Review the timeline

# See all nodes chronologically
deciduous archaeology timeline

# Filter by type
deciduous archaeology timeline --type revisit

# See existing pivot chains
deciduous narratives pivots

# Visual exploration
deciduous serve

Attach Evidence Documents

If you find diagrams, screenshots, or specs that support the archaeology:

deciduous doc attach <goal_id> evidence/old-architecture.png -d "Architecture before refactor"
deciduous doc attach <revisit_id> evidence/perf-report.pdf --ai-describe

Documents provide visual/tangible evidence alongside commit-based grounding.

Querying the Graph

# Current state
deciduous pulse

# Pivot points
deciduous narratives pivots

# Timeline
deciduous archaeology timeline

# By status
deciduous nodes --type revisit

What NOT to Do

• Don't create nodes for every commit. Commits are evidence, not graph nodes.
• Don't create implementation nodes. The graph is about the MODEL, not the code.
• Don't over-structure. Simple narratives might just be: goal -> option -> decision.