How to Read This Tutorial

One Continuous Story

This tutorial follows a single project from start to finish: snowflex, an Elixir library for connecting to Snowflake databases. Rather than working through contrived examples, you'll reconstruct real architectural decisions from a real codebase, then extend it by working on an actual open issue.

Each section builds on the previous one. The decision graph you start building in "Reconstructing History" is the same graph you'll extend in "Live Development" and export in "Sharing." By the end, you'll have a complete, connected decision graph that tells the full story of a real project.

Claude Drives, You Steer

This tutorial emphasizes the LLM-assisted workflow. In most sections, you'll see Claude Code sessions where Claude operates deciduous commands on your behalf. You tell Claude what you want to accomplish—reconstruct this project's history, fix this issue, export this for a PR—and Claude handles the deciduous mechanics.

CLI details appear in "under the hood" sections for readers who want to understand what's happening at the command level. But the primary path through this tutorial assumes you're working with an AI assistant.

You don't need to memorize any deciduous CLI commands to get started.

Your AI assistant already knows them all. The tutorial shows what happens during a session so you understand the system—not so you can type the commands yourself. Think of it like watching someone drive before you get behind the wheel: useful context, not a typing exercise.

What the Sessions Look Like

Throughout the tutorial, you'll see terminal demos that show real Claude Code interactions. They look like this:

Claude Code Session
> /decision-graph I'll analyze the git history and reconstruct the decision graph. Let me start with the earliest commits. git log --oneline --reverse | head -15 a1b2c3d Initial commit - ODBC wrapper d4e5f6g Add basic query support ... deciduous add goal "snowflex connection architecture" -c 90 Created node #1: goal "snowflex connection architecture"

The > line is what you type. Everything else is Claude working. The highlighted commands are what Claude runs, and the dimmer text is terminal output. Narrative text between commands is Claude explaining its thinking.

These sessions are edited for clarity—real sessions include more back-and-forth—but every command shown is a real deciduous command that produces real output.

Tutorial Structure

The tutorial is organized into six sections:

  1. Getting Started — Install deciduous and initialize it in the snowflex repo. See what files Claude gets when you run deciduous init and why they matter.
  2. Reconstructing History — The heart of the tutorial. Use /decision-graph to mine snowflex's git log and build a decision graph covering two years of architectural evolution. Learn about observations, pivots, and the revisit node.
  3. Live Development — Switch from archaeology to forward logging. Use /work to tackle a real open issue (#93), attaching documents and evidence as you go.
  4. Sharing — Export your graph for teammates. Learn the patch-based sync system and the PR workflow with auto-generated writeups and decision visualizations.
  5. Advanced — Themes and tags for organizing large graphs, hooks for automating workflows, and multi-assistant support for teams using different AI tools.
  6. CLI Reference — Every command, every flag, every option. For when you need the specifics or want to script deciduous directly.

You can read straight through or jump to the section you need. If you're brand new, start with Getting Started—it takes about five minutes and gets you to a working setup. If you already have deciduous installed, skip ahead to Reconstructing History to see the tool in action on a real codebase.

Conventions

Terminal Commands

Standalone commands (outside of Claude sessions) are shown with a $ prefix:

$ deciduous nodes --type goal
#1  goal  "snowflex connection architecture"  [active]  c:90
#42 goal  "Fix connection timeout handling"   [active]  c:90

Lines without the $ are output from the command.

Info Boxes

Note

Blue boxes contain additional context or background information.

Warning

Yellow boxes flag important gotchas or things that can go wrong.

Tip

Green boxes contain practical tips and shortcuts.

Node Types

Node types are color-coded throughout the tutorial and in the web viewer:

Prerequisites

This tutorial assumes you:

No prior knowledge of Elixir is needed to follow the snowflex examples. The tutorial focuses on the decision-making process, not the language-specific code. No prior knowledge of decision graphs or graph databases is needed either.

Getting Help

If you get stuck:

Ready to get started? Installing Deciduous →