decision-graph

Decision Graph Construction

You are building a deciduous decision graph - a DAG that captures the evolution of design decisions in a codebase.

Use the deciduous CLI (at ~/.cargo/bin/deciduous) to build the graph. Run deciduous commands in the current directory (not inside the source repo).

For git commands to explore commit history, use git -C <repo-path> to target the source repo.

CRITICAL: Only use information from the repository itself (commits, code, comments, tests). Do not use your prior knowledge about the project. Everything must be grounded in what you find in the repo.

Commit Exploration

Use a layered strategy to find all relevant commits:

Layer 1: See all commits. Start with the full list when building narratives.

git log --oneline --after="..." --before="..." -- path/

Layer 2: Keyword expansion. Once you have narratives, search for spelling variations and related terms you might have missed (e.g., "cache" → "caching", "cached", "LRU", "invalidate"). For each key identifier in your narratives, trace its full lifecycle:

• Introduction
• Changes and modifications
• Renames
• Deprecation or removal
• Replacement by other mechanisms
• Becoming stable/public API

If there's a feature flag controlling the feature, search for commits mentioning that flag.

Layer 3: Follow authors. If a narrative has a key author, check their commits ±1 month from known commits. They often work on related things.

DO NOT:

• git log ... | head -100 — NO. You will miss commits in the middle.
• git log ... | tail -200 — NO. Same problem.
• Start with keyword filtering — NO. You'll miss things with unexpected names.

DO:

• See all commits first, filter mentally while building narratives
• Include "remove", "delete", "disable", "deprecate" in keyword searches — removals explain transitions
• Check the commit count first (| wc -l), but then see them all
• Read full commit messages for any commit whose title mentions an identifier or concept relevant to your narrative — you need precise understanding of what happened to each one you care about

Finding the Story

Not every commit matters. Look for commits that change the model - how the system conceptualizes the problem:

• Existing tests modified (contract changing, not just bugs fixed)
• Data structures replaced or reworked
• Heuristics changed significantly
• New abstractions introduced
• API behavior shifts

Skip commits that are pure implementation (same model, different code) or routine fixes that just add tests.

Among model-changing commits, find the spine: what question keeps getting re-answered? What approach keeps getting replaced or refined? That's your central thread - build the graph around it.

Narrative Tracking

Don't build the graph as you explore. First, collect commits into narratives.

Maintain narratives.md as you explore:

1. For each significant commit, read narratives.md
2. Ask: "Does this commit evolve an existing narrative?"
3. If yes: append the commit to that narrative's section
4. If no: add a new narrative section

Example narratives.md:

## Cache Strategy

**Arc:** The service initially hit the database on every request, which worked until traffic spiked. An in-memory cache solved immediate pain but caused stale data across instances. Redis gave a single source of truth at the cost of network latency.

- a1b2c3d: Add in-memory cache
- e4f5g6h: Cache invalidation issues
- i7j8k9l: Switch to Redis

## API Rate Limiting
- m1n2o3p: Add basic throttling
- ...

The Arc is a one-paragraph story summarizing the narrative's trajectory - what problem started it, what was tried, and where it ended up. Arcs help you see the shape of the story before building the graph.

Before building the graph, take a critical pass over narratives.md:

• Merge narratives that are essentially the same evolving thing
• Ensure each narrative clearly explains how one independent piece evolved
• Note where narratives branch from or feed into each other

Hardening Phase

After building initial narratives, harden them to ensure nothing is missed.

Step 1: Extract concepts per narrative

For each narrative, list the key concepts/APIs/identifiers and their lifecycle stage:

• Introduced: First appearance of the concept
• Changed: Modifications to behavior or implementation
• Renamed/Deprecated/Removed: End of life or replacement
• Marked stable: Became public API or removed "unstable\_" prefix

Example addition to narrative:

## Cache Strategy
Concepts: cache, LRUCache, cacheTimeout, invalidate

Lifecycle:
- cache: introduced (a1b2c3d), changed (e4f5g6h), renamed to LRUCache (x1y2z3)
- cacheTimeout: introduced (e4f5g6h), removed (i7j8k9l)
- LRUCache: introduced via rename (x1y2z3), marked stable (p1q2r3)

Commits:
- a1b2c3d: Add in-memory cache
- ...

Step 2: Exhaustive search per concept

For each concept, search full commit messages (not just subject lines):

git log --all --after="..." --before="..." --grep="<concept>" --format="%H %s" -- path/

For each match, read the full commit message:

git show <sha> --format="%B" --no-patch

Step 3: Rewrite narratives with gaps filled

Rewrite narratives.md integrating any newly discovered commits. The rewritten version should:

• Include ALL commits found for each concept
• Update the lifecycle tracking for each concept
• Ensure the arc is complete (if something was introduced, when was it changed/removed?)

If a concept has an incomplete arc (e.g., introduced but never removed, yet it's not in current code), investigate further.

Before building the graph, take one more critical pass over narratives.md:

• Merge narratives that are essentially the same evolving thing
• Ensure each narrative clearly explains how one independent piece evolved
• Note where narratives branch from or feed into each other

Cross-Narrative Connections

When building the graph, don't just branch everything from the goal. Capture how narratives relate:

Branch from the spine, not goal: If a narrative arose from work in another narrative, branch from that work.

• Wrong: goal → "How to preserve state?"
• Right: outcome("timeout works") → "How to preserve state?" (the question arose after implementing timeout)

Observations feed back: If an observation in one narrative influenced decisions in another, add an edge.

• Example: An observation about nested boundary timing might inform heuristics refinement in the main narrative

Keep truly independent things from goal: If a narrative is genuinely a separate concern that doesn't arise from other work, branching from goal is appropriate.

Parallel vs Sequential: When connecting narratives, ask: "Did A cause B, or did they happen to occur around the same time?"

• If A genuinely caused or enabled B → connect them sequentially (A → B)
• If A and B developed independently but happened in parallel → don't force a connection; both can branch from the same parent

After consolidating, build the graph - one decision chain per narrative, with cross-links where they connect.

Node Types

| Type | Purpose | | --------------- | ----------------------------------------------------- | | goal | High-level objective being pursued | | decision | A choice point with multiple possible paths | | option | A possible approach to a decision | | observation | Learning, insight, or new information discovered | | action | Something that was done (must reference a commit) | | outcome | Result or consequence of an action | | revisit | Pivot point where a previous approach is reconsidered |

CLI Commands

# Add nodes (returns node ID)
deciduous add goal "Title of the goal"