narratives git:20260926.88df937A

Immutable. This exact content never changes and is served at /api/v1/blob/4bbe05cddc16eefb.

---
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>`.