narratives ยท diff
git:20260408.c06a5da to git:20260926.88df937
4 added, 0 removed. Audit A to A.
---
name: narratives
description: Understand how a system evolved - narratives are the source of truth
compatibility: opencode
---
# Narrative Tracking
**Narratives are the source of truth. Commits are just evidence.**
## Step 1: Initialize narratives file
```bash
deciduous narratives init
```
This creates `.deciduous/narratives.md` pre-populated with your active goal titles.
## Step 2: Understand the system first
Before looking at git, read the code. Ask: **What are the major pieces of this system?**
Each major piece probably has a narrative behind it.
## Step 3: Fill in the narratives
Edit `.deciduous/narratives.md`. For each section:
1. Describe the **current state** (how it works today)
2. Infer the **evolution** (how it likely got this way)
3. Identify **PIVOTs** (when the conceptual model changed)
4. Find evidence (PRs, commits, docs) - optional
5. Check attached documents (`deciduous doc list`)
Signs of a pivot:
- Two approaches coexisting (migration in progress)
- Comments explaining "we used to do X"
- Config for old + new system
- Deprecation warnings
## Step 4: Review narratives
```bash
deciduous narratives show
```
## Step 5: Check existing pivots
```bash
deciduous narratives pivots
```
## Output Format
Each narrative section in `.deciduous/narratives.md`:
```markdown
## <Name>
> <One sentence: what this piece of the system does>
**Current state:** <How it works today>
**Evolution:**
1. <First approach> - <why>
2. **PIVOT:** <what changed> - <why it changed>
3. <Current approach> - <why this is better>
**Evidence:** <Optional: PRs, commits, docs>
**Connects to:** <Other narratives this influenced>
**Status:** active | superseded | abandoned
```
## What Makes a Good Narrative
- Coherent story about ONE design aspect
- Explains HOW something works and WHY it evolved
- Would help a new team member understand the system
- NOT a list of commits or feature changelog
## Next Step
After narratives are written, run `/archaeology` to transform them into a queryable decision graph.
+ ## 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>`.
+