Decision Graph Concepts

A decision graph is a directed acyclic graph (DAG) where nodes represent things that happened and edges represent relationships between them. This chapter covers the building blocks.

Node Types

Every node has a type that describes its role in the decision-making process.

Type	Purpose
goal	High-level objective — what you are trying to achieve
option	A possible approach to explore for a goal
decision	Choosing which option to pursue
action	Implementation step — work being done
outcome	Result of an action — what happened
observation	A discovery or insight — attaches anywhere relevant
revisit	Pivot point — connects an old approach to a new one

When to use each type

Goal: When the user asks for something new or a high-level objective is identified.
Option: When exploring possible approaches before choosing one. Options always come from a goal.
Decision: When an option is actually chosen. Decisions come after options, not before.
Action: When you are about to write or change code. Log it before the work.
Outcome: When work is complete. Link it back to the action that produced it.
Observation: When you notice something interesting — a constraint, a codebase pattern, a risk. Use the -d flag for a detailed description.
Revisit: When a previous approach is being abandoned and replaced. Links old decisions to new ones.

The Canonical Flow

Every decision follows this path through the graph:

goal → options → decision → actions → outcomes

goal leads to option nodes (possible approaches)
option nodes lead to a decision (choosing which to pursue)
decision leads to action nodes (implementing the choice)
action nodes lead to outcome nodes (results)
observation attaches anywhere relevant
revisit connects old approaches to new ones during pivots

Goals do not lead directly to decisions. There must be options first. Options do not come after decisions. Decision nodes should only be created when an option is actually chosen.

Edge Types

Edges describe the relationship between two nodes.

Type	Meaning	Typical usage
`leads_to`	Natural progression	goal → option, action → outcome
`chosen`	Option was selected	option → decision
`rejected`	Option was not selected	option → decision (with reason)
`requires`	Dependency relationship	action → another action
`blocks`	Prevents progress	observation → action
`enables`	Makes something possible	action → outcome

Note: A supersedes edge type is auto-created by the revisit/archaeology system (e.g., deciduous archaeology pivot). It is not a valid parameter for deciduous link.

Status	Meaning
`pending`	Not yet started
`active`	Current truth — how things work today
`completed`	Finished successfully
`rejected`	Considered and rejected
`superseded`	Replaced by a newer approach
`abandoned`	Tried and rejected — dead end

$ deciduous nodes --status active
ID Type Title Status Confidence
1 goal Add user authentication active 90%
5 decision Use JWT for API auth active 85%

$ deciduous nodes --status superseded
ID Type Title Status Confidence
3 decision Use session cookies superseded 75%

Confidence Levels

Every node carries a confidence value from 0 to 100, reflecting how certain you are about it.

Range	Meaning
90-100	High confidence — well-understood, clear requirement
70-89	Moderate confidence — reasonable approach, some unknowns
50-69	Low confidence — exploratory, uncertain
0-49	Very low — speculative, needs validation

Confidence helps future sessions prioritize which decisions to revisit. A low-confidence decision is a natural candidate for re-evaluation.

The Revisit Pattern

When a design approach is abandoned and replaced, a revisit node captures the pivot:

An observation identifies why the old approach failed
A revisit node links to that observation
The revisit leads to the new decision
The old decision is marked superseded

This captures why you changed direction, not just what changed.

Terminal

$ deciduous add observation "JWT tokens too large for mobile clients" -c 90
Created node 12 (type: observation) [confidence: 90%] [branch: main]
$ deciduous add revisit "Reconsidering token strategy" -c 85
Created node 13 (type: revisit) [confidence: 85%] [branch: main]
$ deciduous link 12 13 -r "forced rethinking"
Linked 12 → 13 (leads_to) "forced rethinking"
$ deciduous status 5 superseded
Updated node 5 status to superseded

Sessions and Chains

Sessions group nodes by time proximity. Nodes created within 4 hours of each other belong to the same session. A gap longer than 4 hours starts a new session.

Chains are connected components of the graph. Starting from root nodes (goals or nodes with no incoming edges), BFS traverses all connected nodes. Chains group related decisions together — “show me everything related to authentication.”

Both concepts are used by the web viewer to organize and display your decision history.

Deciduous