narratives

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:

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

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.