This tutorial was AI-generated and is being fleshed out. Content may be incomplete or change.

Connecting Nodes

Nodes without connections are just a list. Let's turn them into a proper graph.

The Link Command

Use deciduous link to create edges between nodes:

$ deciduous link 1 2 -r "Need to decide approach"
Created edge: #1 -> #2 (leads_to) "Need to decide approach"

This creates an edge from node #1 (our goal) to node #2 (our decision), with a rationale explaining why they're connected.

Building the Decision Flow

Let's connect all our nodes:

# Connect decision to its options
$ deciduous link 2 3 -r "Stateless, scales well"
Created edge: #2 -> #3 (leads_to) "Stateless, scales well"

$ deciduous link 2 4 -r "Simpler but requires server state"
Created edge: #2 -> #4 (leads_to) "Simpler but requires server state"

Now let's say we chose JWT. We'll create an action and link it with the chosen edge type:

$ deciduous add action "Implementing JWT authentication" -c 85
Created node #5: action "Implementing JWT authentication"

$ deciduous link 2 5 --edge-type chosen -r "Stateless preferred for microservices"
Created edge: #2 -> #5 (chosen) "Stateless preferred for microservices"

And when implementation is complete:

$ deciduous add outcome "JWT auth working, tests passing" -c 95
Created node #6: outcome "JWT auth working, tests passing"

$ deciduous link 5 6 -r "Implementation complete"
Created edge: #5 -> #6 (leads_to) "Implementation complete"

Viewing the Graph

Let's see all our edges:

$ deciduous edges
From  To   Type       Rationale
────────────────────────────────────────────────────────────────
1     2    leads_to   Need to decide approach
2     3    leads_to   Stateless, scales well
2     4    leads_to   Simpler but requires server state
2     5    chosen     Stateless preferred for microservices
5     6    leads_to   Implementation complete

Now we have a complete decision chain:

Goal → Decision → Options + Chosen Action → Outcome

Edge Types

Deciduous supports several edge types to capture different relationships:

Type Meaning When to Use
leads_to Natural progression Default for most connections
chosen Selected this option When picking an option to implement
rejected Did not select When explicitly rejecting an option
requires Dependency When one thing needs another first
blocks Preventing progress When something is blocked
enables Makes possible When one thing unlocks another

The Connection Rules

Golden Rule

Every node (except root goals) should connect to something. Orphan nodes lose the context that makes them valuable.

Node Type Should Connect To
goal Can be root (no parent needed)
decision Parent goal or decision
option Parent decision
action Parent decision (with chosen edge)
outcome Parent action or goal
observation Related node (any type)

Connect Immediately

The best practice is to link nodes immediately after creating them. Don't create a bunch of nodes and then try to remember how they connect later.

# Good: Create and connect immediately
$ deciduous add action "Implementing JWT" -c 85
$ deciduous link 2 5 --edge-type chosen -r "Best for our architecture"

# Bad: Creating nodes without connecting
$ deciduous add action "Implementing JWT" -c 85
$ deciduous add action "Adding tests" -c 80
$ deciduous add outcome "Feature complete" -c 95
# ... now you have to remember how they all connect