Deciduous works because it captures decisions as they happen, not after the fact. This chapter covers the core workflow rules, what to log (and what not to), session recovery, the revisit pattern for pivots, and linking commits to the graph.
BEFORE you do something – log what you’re about to do
AFTER it succeeds or fails – log the outcome
CONNECT immediately – link every node to its parent
If you skip the “before” step, you lose the reasoning. If you skip the “after” step, you lose the result. If you skip the connection, the graph is just a pile of disconnected notes.
The decision graph records the project’s decisions, not the AI’s internal process. A good rule of thumb: if it would appear on a project timeline or in a PR description, log it.
Do log:
Trigger
Node Type
Example
User asks for a feature
goal
“Add dark mode support”
Exploring approaches
option
“CSS custom properties for theming”
Choosing an approach
decision
“Use CSS custom properties over Tailwind dark:”
Writing or changing code
action
“Implement theme toggle component”
Something worked or failed
outcome
“Dark mode working, 6 tests passing”
A technical finding
observation
“Existing styles use hardcoded hex colors”
Do not log:
Reading or exploring the codebase (“Analyzing project structure”)
Your planning process (“Evaluating options internally”)
Tool usage (“Running tests to check status”)
Context gathering (“Reviewing the auth module”)
Meta-commentary (“Starting work on this task”)
These are the AI’s internal process, not project decisions. They add noise without value.
When an approach fails, you don’t just start over. You create a revisit node that explicitly connects the failed approach to the new one. This preserves the why – future readers will see what was tried and why it was abandoned.
The graph now tells the full story: we tried synchronous image crate processing, it was too slow (4.2s), we discovered the root cause (no SIMD), and pivoted to async libvips (380ms). Anyone reading this later gets the complete reasoning, not just the final code.
The --commit HEAD flag captures the commit hash and links it to the node. The web viewer will display commit messages, authors, and dates alongside the decision that produced them.
Sessions end. Context compacts. But the graph survives. At the start of a new session, recover context by inspecting the existing graph:
Claude Code — new session, next day
Claude
Recovering context from the decision graph...
$ deciduous nodes
ID Type Status Conf Title
──────────────────────────────────────────────────────────────────────
10 goal active 90% Add file upload with 10MB image limit and thumbnail generation
11 option active 70% ImageMagick via std::process::Command for thumbnails
12 option active 80% image crate (pure Rust) for thumbnails
13 decision superseded 85% Use image crate — no external dependencies, pure Rust
14 action active 80% Implement upload endpoint with image crate thumbnails
15 outcome active 40% image crate too slow — 4.2s per thumbnail at 10MB, blocks request
16 observation active 90% image crate resizing is single-threaded, no SIMD optimization
17 revisit active 85% Reconsidering thumbnail strategy — sync processing too slow
18 option active 85% Background job with libvips for fast thumbnail generation
19 decision active 90% Use async job queue + libvips for thumbnail generation
20 action active 85% Implement upload endpoint + background thumbnail worker
21 outcome active 95% Upload + async thumbnails working — 120ms upload, 380ms thumbnail job
22 action active 95% Committed upload + thumbnail implementation
Claude
$ deciduous show 10
Node #10 goal
────────────────────────────────────────
Title: Add file upload with 10MB image limit and thumbnail generation
Status: active
Confidence: 90%
Branch: feature-uploads
Connections
Outgoing (3):
here ─[possible approach]→ #11: ImageMagick via std::process::Command for thumbnails
here ─[possible approach]→ #12: image crate (pure Rust) for thumbnails
here ─[new approach after revisit]→ #18: Background job with libvips for fast thumbnail generation
Claude
I can see the full history: we tried the image crate (node 13, now superseded), it was too slow at 4.2s per thumbnail (node 15), so we pivoted to async libvips (node 17 revisit, node 19 decision). The implementation is complete with 12 tests passing (node 21). Let me check if there's remaining work on this goal.
The deciduous edges command is also valuable for understanding the connections between nodes:
Terminal — checking edges
$ deciduous edges
From To Reason
──────────────────────────────────────────────────────────────────
10 11 possible approach
10 12 possible approach
10 18 new approach after revisit
12 13 chosen — no external deps
11 13 rejected — requires ImageMagick installed
13 14 implementing chosen approach
14 15 implementation result — failed
15 16 root cause
16 17 forced rethinking
18 19 chosen after performance failure of sync approach
17 19 new direction
19 20 implementing chosen approach
20 21 implementation result
20 22 committed to git
Every edge tells you why two nodes are connected. The graph is not just a list of things that happened – it’s a map of the reasoning that produced them.