Telling the Story with Narratives
The graph captures structure. Narratives capture the human-readable story.
A decision graph with 56 nodes and 66 edges is a powerful data structure, but it's not something you hand to a new team member and say "read this." Narratives are the layer on top—prose documents that explain the evolution of a system in plain language, grounded in the graph's structure.
Generating Narratives
After the archaeology session has built the graph, you ask Claude to tell the story. Claude scaffolds a narrative document, fills it in from the graph, and saves it for future reference.
- Create an Elixir library for querying Snowflake
- Transport layer evolution
- Authentication and key management
writes prose connecting the evolution story to specific graph nodes]
Snowflex started in June 2019 as a thin wrapper around Erlang's ODBC driver (nodes #1–5). It worked for single connections but couldn't handle concurrency, leading to the ConnectionPool era (nodes #6–9). The pool solved concurrency but the API was cumbersome (node #10), so the team adopted a module-based API modeled after Ecto.Repo (nodes #11–14).
The big pivot came in early 2021 (revisit #34). ODBC had accumulated four problems: session expiry, UTF-16 corruption, Apple Silicon incompatibility, and memory issues. The team chose HTTP REST with a transport behavior pattern (#37) over a rigid direct client (#38), producing v1.0 — a modern adapter with no native dependencies.
I've written the full narrative to
.deciduous/narratives.md with node references throughout.The narrative references specific node IDs so readers can cross-reference with the graph. This is intentional—the narrative is the story, the graph is the evidence.
Finding Pivot Points
The most architecturally significant moments in any project are the pivots — where the team changed direction. Claude can surface these instantly:
#34: Reconsider ODBC as transport - switch to HTTP REST API
32 (outcome) → 33 (observation) → 34 (revisit) → 36 (decision)
Reason: ODBC too fragile for production
#46: Reconsider single-key auth - support multiple key formats
44 (outcome) → 45 (observation) → 46 (revisit) → 48 (decision)
Reason: Enterprise customers need key rotation
Each pivot chain traces the path from an old outcome, through the observation that revealed the problem, through the revisit that reconsidered the approach, to the new decision that replaced it.
Archaeology Timeline
For a chronological view, Claude can pull a timeline of the graph:
The timeline gives you the "when" that complements the graph's "what" and "why." Combined with narratives and pivot chains, you have a complete picture of a project's evolution.
Narratives bridge the gap between the structured graph and human understanding. The graph is for machines to query; narratives are for humans to read. Use the graph when you need precision and traceability. Use narratives when you need to onboard a teammate or write a design document.