archaeology

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

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.