archaeology ยท diff
git:20260408.c06a5da to git:20260926.88df937
4 added, 0 removed. Audit A to A.
---
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>`.
+