By 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
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:
- Describe the current state (how it works today)
- Infer the evolution (how it likely got this way)
- Identify PIVOTs (when the conceptual model changed)
- Find evidence (PRs, commits, docs) - optional
- 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
deciduous narratives show
Step 5: Check existing pivots
deciduous narratives pivots
Output Format
Each narrative section in .deciduous/narratives.md:
## <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.