Decision Graph (dg)

The knowledge graph that lives with your code. Capture decisions, strategies, and institutional knowledge in markdown files that version control alongside your codebase.

"Why did we choose PostgreSQL?" "Who decided on the France expansion?" "What's our caching strategy?"

Stop losing decisions in Slack threads and forgotten meetings.

For Humans and AI

Decision Graph is built for the async-first, AI-augmented workplace:

• Colocated with code - decisions live in git, reviewed in PRs, deployed with releases
• AI-native - structured formats that LLMs can read, query, and update
• Framework-driven - proven templates (SPADE, Six-Pager, 7 Powers, RICE)
• Graph-connected - decisions link to strategies, incidents, customers, feedback

Key Features

Installation

With Nix/Devenv (Recommended)

Initialize a new project with Decision Graph:

nix flake init -t github:decisiongraph/dg
devenv shell

Or add to existing devenv project:

# devenv.yaml
inputs:
  dg:
    url: github:decisiongraph/dg

# devenv.nix
{ pkgs, inputs, ... }:
let system = pkgs.stdenv.hostPlatform.system;
in {
  imports = [ inputs.dg.devenvModules.default ];
  packages = [ inputs.dg.packages.${system}.default ];
}

With Homebrew

brew install decisiongraph/tap/dg

With Cargo

cargo install --git https://github.com/decisiongraph/dg

From Releases

Download pre-built binaries from Releases.

Quick Start

# Initialize in your project
dg init

# Create records
dg new decision "Use PostgreSQL for primary database"
dg new adr "Adopt event sourcing for order service"
dg new incident "API outage 2024-01-15"

# Link records
dg link ADR-001 implements DEC-001

# Query
dg list
dg search "database"
dg show DEC-001

# Visualize
dg graph

Record Types

Commands

# Create & Edit
dg new <type> "Title"     # Create record
dg new <type> "Title" --draft  # Multi-player mode (finalize before merge)
dg finalize               # Convert draft IDs to permanent
dg edit ID                # Edit in $EDITOR

# Query
dg list [--type TYPE] [--status STATUS] [--tag TAG]
dg search "query" [-c]    # -c includes content
dg show ID [-l]           # -l shows linked records
dg context "topic"        # LLM-friendly context dump

# Links & Status
dg link ID1 <type> ID2    # Add link
dg unlink ID1 <type> ID2  # Remove link
dg status ID <status>     # Update status
dg resolve ID             # Resolve incident

# Analysis
dg graph [ID] [-d DEPTH]  # Visualize relationships
dg why ID                 # Trace dependencies backward
dg impact ID              # What depends on this?
dg orphans                # Records with no links
dg principles             # List core records
dg timeline               # Chronological view

# Validate & Format
dg lint [--strict]        # Check for errors
dg fmt [--check]          # Format markdown
dg validate               # Full validation

# Maintain
dg stats                  # Statistics
dg reindex                # Rebuild index
dg export [-f json|csv]   # Export records
dg diff                   # Changes since last commit
dg changelog              # Generate changelog
dg retype ID <new-type>   # Change record type
dg suggest                # Suggest missing decisions from git

# Web & CI
dg serve [--port 3000] [--open]  # Web UI
dg build                  # Generate static site
dg setup-ci               # GitHub Actions for multi-player

# People
dg users                  # List users
dg teams                  # List teams
dg tasks [--user USER]    # Action items
dg history user <name>    # User contribution history

Link Types

Statuses

draft → proposed → accepted → deprecated / superseded

Additional: active, open, closed, resolved, cancelled

Web UI

Launch the local web server:

dg serve --open

Features:

• Browse all records with search and filtering
• View record relationships in interactive graph
• Edit records with live preview
• Timeline view of record history
• User/team pages with assigned action items
• Stats dashboard

Claude Code Integration

When using with devenv, Claude automatically:

• Searches for related records before making changes
• Captures decisions during conversations
• Links new records to existing context
• Asks for clarification when conflicts found

Skills

Use slash commands to create records:

• /decision - business decision
• /adr - architecture decision
• /incident - post-mortem
• /runbook - operational guide
• /meeting - meeting notes
• /context - search before acting

Hooks

• Session start: Reminds about decision graph context
• Session stop: Prompts to capture uncaptured decisions

File Format

Records are markdown with YAML frontmatter:

---
type: decision
id: DEC-001
title: "Use PostgreSQL for primary database"
status: accepted
created: 2024-01-15
updated: 2024-01-20
authors: [alice]
tags: [database, infrastructure]
links:
  implements: [STR-001]
  enables: [ADR-002]
---

# Use PostgreSQL for primary database

## Setting
...

Directory Structure

docs/
├── decisions/      # Record files
├── .templates/     # Record templates
└── .index.json     # Auto-generated index
.claude/
├── hooks/          # Session hooks
└── skills/         # Slash commands

Shell Completions

# Bash
dg completions bash > ~/.local/share/bash-completion/completions/dg

# Zsh
dg completions zsh > ~/.zfunc/_dg

# Fish
dg completions fish > ~/.config/fish/completions/dg.fish

Development

cargo build           # Build
cargo test            # Test
cargo build --release # Release build
cargo install --path . # Install locally

Frameworks

Decision Graph includes templates for proven decision-making frameworks:

• SPADE (Square): Setting, People, Alternatives, Decide, Explain
• Six-Pager (Amazon): Narrative memos for strategy
• 7 Powers (Hamilton Helmer): Competitive moat analysis
• RICE (Intercom): Reach, Impact, Confidence, Effort prioritization
• ADR (Michael Nygard): Architecture Decision Records
• DACI (Atlassian): Driver, Approver, Contributors, Informed
• OST (Teresa Torres): Opportunity Solution Trees
• Scorecard (Who method): Structured hiring
• 5 Whys: Root cause analysis for incidents

License

AGPL-3.0