taurean.bryant.land
a template starter repo for sveltekit projects
2.8 kB
126 lines
1---
2name: archaeology
3description: Transform narratives into a queryable decision graph
4compatibility: opencode
5---
6
7# Archaeology
8
9**Transform narratives into a queryable decision graph.**
10
11Run `/narratives` first to create `.deciduous/narratives.md`.
12
13## Step 1: Read the narratives
14
15```bash
16deciduous narratives show
17```
18
19For each narrative, you'll create a subgraph.
20
21## Step 2: Create root goals
22
23For each narrative, create a backdated goal:
24
25```bash
26deciduous add goal "<Narrative title>" -c 90 --date "YYYY-MM-DD"
27```
28
29## Step 3: Build initial approaches
30
31```bash
32deciduous add decision "<First approach>" -c 85 --date "YYYY-MM-DD"
33deciduous link <goal> <decision> -r "Initial design"
34```
35
36## Step 4: Create pivots with `archaeology pivot`
37
38For each **PIVOT** in a narrative, use the atomic pivot command:
39
40```bash
41deciduous archaeology pivot <from_id> "<what was learned>" "<new approach>" -c 85 -r "<why it failed>"
42```
43
44This automatically creates:
45
46- observation node (what was learned)
47- revisit node (reconsidering the old approach)
48- decision node (the new approach)
49- All 3 linking edges
50- Marks the old approach as superseded
51
52Preview before executing:
53
54```bash
55deciduous archaeology pivot <from_id> "observation" "new approach" --dry-run
56```
57
58## Step 5: Connect narratives
59
60When narratives reference each other:
61
62```bash
63deciduous link <auth_observation> <ratelimit_decision> \
64 -r "Auth failures drove rate limit redesign"
65```
66
67## Step 6: Mark superseded paths
68
69For nodes that were replaced but not part of a pivot:
70
71```bash
72# Single node
73deciduous archaeology supersede <id>
74
75# Node and all descendants
76deciduous archaeology supersede <id> --cascade
77```
78
79## Step 7: Review the timeline
80
81```bash
82# See all nodes chronologically
83deciduous archaeology timeline
84
85# Filter by type
86deciduous archaeology timeline --type revisit
87
88# See existing pivot chains
89deciduous narratives pivots
90
91# Visual exploration
92deciduous serve
93```
94
95## Attach Evidence Documents
96
97If you find diagrams, screenshots, or specs that support the archaeology:
98
99```bash
100deciduous doc attach <goal_id> evidence/old-architecture.png -d "Architecture before refactor"
101deciduous doc attach <revisit_id> evidence/perf-report.pdf --ai-describe
102```
103
104Documents provide visual/tangible evidence alongside commit-based grounding.
105
106## Querying the Graph
107
108```bash
109# Current state
110deciduous pulse
111
112# Pivot points
113deciduous narratives pivots
114
115# Timeline
116deciduous archaeology timeline
117
118# By status
119deciduous nodes --type revisit
120```
121
122## What NOT to Do
123
124- **Don't create nodes for every commit.** Commits are evidence, not graph nodes.
125- **Don't create implementation nodes.** The graph is about the MODEL, not the code.
126- **Don't over-structure.** Simple narratives might just be: goal -> option -> decision.