archaeology git:20260926.88df937A

Immutable. This exact content never changes and is served at /api/v1/blob/58b6c2a8af0c5113.

---
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

```bash
deciduous narratives show
```

For each narrative, you'll create a subgraph.

## Step 2: Create root goals

For each narrative, create a backdated goal:

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

## Step 3: Build initial approaches

```bash
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:

```bash
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:
```bash
deciduous archaeology pivot <from_id> "observation" "new approach" --dry-run
```

## Step 5: Connect narratives

When narratives reference each other:

```bash
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:

```bash
# Single node
deciduous archaeology supersede <id>

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

## Step 7: Review the timeline

```bash
# 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:

```bash
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

```bash
# 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.

## Working Alongside Other Agents

If other agents work on this at the same time (one narrative each, say), split the work and hand off on the deciduous message board, never in a scratch file: post with `deciduous board post --as <label> -s "..." -m "@other ..."` (or the `post_message` MCP tool), read `deciduous board read --unanswered <label>` before you start and before you finish, and answer with `--reply-to <id>`.