taurean.bryant.land
a template starter repo for sveltekit projects
2.0 kB
85 lines
1---
2name: narratives
3description: Understand how a system evolved - narratives are the source of truth
4compatibility: opencode
5---
6
7# Narrative Tracking
8
9**Narratives are the source of truth. Commits are just evidence.**
10
11## Step 1: Initialize narratives file
12
13```bash
14deciduous narratives init
15```
16
17This creates `.deciduous/narratives.md` pre-populated with your active goal titles.
18
19## Step 2: Understand the system first
20
21Before looking at git, read the code. Ask: **What are the major pieces of this system?**
22
23Each major piece probably has a narrative behind it.
24
25## Step 3: Fill in the narratives
26
27Edit `.deciduous/narratives.md`. For each section:
28
291. Describe the **current state** (how it works today)
302. Infer the **evolution** (how it likely got this way)
313. Identify **PIVOTs** (when the conceptual model changed)
324. Find evidence (PRs, commits, docs) - optional
335. Check attached documents (`deciduous doc list`)
34
35Signs of a pivot:
36
37- Two approaches coexisting (migration in progress)
38- Comments explaining "we used to do X"
39- Config for old + new system
40- Deprecation warnings
41
42## Step 4: Review narratives
43
44```bash
45deciduous narratives show
46```
47
48## Step 5: Check existing pivots
49
50```bash
51deciduous narratives pivots
52```
53
54## Output Format
55
56Each narrative section in `.deciduous/narratives.md`:
57
58```markdown
59## <Name>
60
61> <One sentence: what this piece of the system does>
62
63**Current state:** <How it works today>
64
65**Evolution:**
66
671. <First approach> - <why>
682. **PIVOT:** <what changed> - <why it changed>
693. <Current approach> - <why this is better>
70
71**Evidence:** <Optional: PRs, commits, docs>
72**Connects to:** <Other narratives this influenced>
73**Status:** active | superseded | abandoned
74```
75
76## What Makes a Good Narrative
77
78- Coherent story about ONE design aspect
79- Explains HOW something works and WHY it evolved
80- Would help a new team member understand the system
81- NOT a list of commits or feature changelog
82
83## Next Step
84
85After narratives are written, run `/archaeology` to transform them into a queryable decision graph.