Working with Nodes

This chapter covers the core workflow: adding nodes, linking them, updating status, and maintaining the graph.

Adding Nodes

Create nodes with deciduous add <type> "title". The type must be one of: goal, option, decision, action, outcome, observation, or revisit.

Terminal

$ deciduous add goal "Add user authentication" -c 90
Created node 1 (type: goal) [confidence: 90%] [branch: main]

$ deciduous add option "Use JWT tokens" -c 80
Created node 2 (type: option) [confidence: 80%] [branch: main]

$ deciduous add action "Implementing JWT middleware" -c 85 -f "src/auth/jwt.rs,src/auth/mod.rs"
Created node 3 (type: action) [confidence: 85%] [branch: feature-auth]

$ deciduous add outcome "JWT auth working — 14 tests passing" -c 95 --commit HEAD
Created node 4 (type: outcome) [confidence: 95%] [branch: feature-auth] [commit: a1b2c3d]

$ deciduous add observation "Existing bcrypt helper in utils/" -c 85 -d "Found password hashing utilities already in the codebase that we can reuse."
Created node 5 (type: observation) [confidence: 85%] [branch: feature-auth]

All Flags

Flag	Description
`-c, --confidence <0-100>`	Confidence level for this node
`-p, --prompt "..."`	Short user prompt that triggered this work
`--prompt-stdin`	Read the prompt from stdin (for multi-line prompts)
`-f, --files "a.rs,b.rs"`	Associate source files with this node
`-b, --branch <name>`	Git branch (auto-detected by default)
`--commit <hash\|HEAD>`	Link to a git commit
`--date "YYYY-MM-DD"`	Backdate the node (useful for archaeology)
`--no-branch`	Skip auto-detection of git branch
`-d, --description "..."`	Detailed description (especially useful for observations)

Capturing Verbatim Prompts

For goal nodes, capture the user’s exact request — not a summary. This enables full context recovery in future sessions.

Terminal

$ deciduous add goal "Add rate limiting" -c 90 --prompt-stdin << 'EOF'
I need to add rate limiting to the API. Should be per-user based on
auth token, with a 100 req/min default and configurable per-plan limits.
EOF
Created node 1 (type: goal) [confidence: 90%] [branch: main]

You can also update the prompt on an existing node:

Terminal

$ deciduous prompt 1 "The full verbatim user request goes here..."
Updated prompt for node 1

Linking Nodes

Create edges between nodes with deciduous link <from> <to>. Always link immediately after creating a node.

Terminal

$ deciduous link 1 2 -r "Possible approach"
Linked 1 → 2 (leads_to) "Possible approach"

$ deciduous link 2 4 -r "Chosen: mature crate, full control" --edge-type chosen
Linked 2 → 4 (chosen) "Chosen: mature crate, full control"

$ deciduous link 3 5 --edge-type rejected -r "Too much complexity for our scale"
Linked 3 → 5 (rejected) "Too much complexity for our scale"

Connection Rules

Root goal nodes are the only valid orphans. Every other node type must be linked immediately:

When you create…	Link to…
option	Its parent goal
decision	The option(s) it chose between
action	The decision that spawned it
outcome	The action that produced it
observation	The related goal or action
revisit	The decision/outcome being reconsidered

Updating Status

Change a node’s status with deciduous status <id> <status>.

Terminal

$ deciduous status 3 completed
Updated node 3 status to completed

$ deciduous status 7 superseded
Updated node 7 status to superseded

$ deciduous status 9 abandoned
Updated node 9 status to abandoned

Valid status values: pending, active, completed, rejected, superseded, abandoned.

Showing Node Details

Use deciduous show <id> to view a node’s full details, including connections.

Terminal

$ deciduous show 1
Node #1 goal
────────────────────────────────────────
Title: Add user authentication
Status: active
Confidence: 90%
Branch: main

Connections
Outgoing (2):
here ─[possible approach]→ #2: Use JWT tokens
here ─[possible approach]→ #3: Use session cookies

Querying Nodes and Edges

Terminal

$ deciduous nodes
ID Type Title Status Confidence
1 goal Add user authentication active 90%
2 option Use JWT tokens active 80%
3 option Use session cookies rejected 75%
4 decision Use JWT for API auth active 85%
5 action Implementing JWT middleware completed 85%

$ deciduous nodes --type goal
ID Type Title Status Confidence
1 goal Add user authentication active 90%

$ deciduous nodes -b feature-auth
ID Type Title Status Confidence
5 action Implementing JWT middleware completed 85%
6 outcome JWT auth working — 14 tests completed 95%

$ deciduous edges
1 → 2 (leads_to) "Possible approach"
1 → 3 (leads_to) "Possible approach"
2 → 4 (chosen) "Mature crate, full control"
4 → 5 (leads_to) "Implementation"
5 → 6 (leads_to) "Complete"

$ deciduous edges --to 4
2 → 4 (chosen) "Mature crate, full control"

Deleting and Unlinking

Remove edges with deciduous unlink and nodes with deciduous delete.

Terminal

$ deciduous unlink 5 12
Removed edge 5 → 12

$ deciduous delete 12 --dry-run
Would delete node 12 (observation: "Stale finding") and 2 connected edges

$ deciduous delete 12
Deleted node 12 and 2 connected edges

Use --dry-run to preview what would be removed before committing to a deletion.

Linking Commits

After every git commit, link it to the decision graph with --commit HEAD:

Terminal

Claude

$ deciduous add action "Implementing JWT middleware" -c 85

Created node 5 (type: action) [confidence: 85%] [branch: feature-auth]

Claude

Writing src/auth/jwt.rs and src/auth/refresh.rs...

Claude

$ git commit -m "feat: add JWT auth middleware"

Claude

$ deciduous add outcome "JWT auth working — 14 tests passing" -c 95 --commit HEAD

Created node 6 (type: outcome) [confidence: 95%] [commit: a1b2c3d] [branch: feature-auth]

$ deciduous link 5 6 -r "Implementation complete"

Linked 5 → 6 (leads_to) "Implementation complete"

The web viewer displays commit messages, authors, and dates for linked nodes.

The Core Pattern

The golden rule for working with nodes:

Before you write code – log what you are about to do (action)
After it works – log the result (outcome)
Always – link every node to its parent immediately

Keyboard shortcuts

Deciduous