# Deciduous Roadmap
## Completed
### v0.8.x - Prompt Tracking & Template Sync (December 2024)
- [x] `--prompt` flag for capturing user prompts on nodes
- [x] Prompt display in web viewer with word-wrap
- [x] Template sync fix - init.rs templates match actual command files
- [x] `deciduous update` no longer destroys custom content
### v0.6.0 - Multi-User Graph Sync (December 2024)
- [x] jj-inspired dual-ID model with `change_id` (UUID) for globally unique nodes
- [x] `deciduous diff export` - export nodes as shareable JSON patches
- [x] `deciduous diff apply` - apply patches from teammates (idempotent)
- [x] `deciduous diff status` - list available patches
- [x] `deciduous migrate` - add change_id columns for sync
- [x] Auto-migration on database open
- [x] Bootstrapped templates include multi-user sync documentation
### Legacy Cleanup
- [x] All templates use `deciduous` binary (no more `losselot` references)
- [x] Live graph URLs point to correct project
- [x] `src/init.rs` uses installed binary path
### Code Tracking & File Associations (Partial)
- [x] `--files` flag for associating files with nodes
---
## In Progress / High Priority
### Subagent System for Codebase Domains
*Specialized agents for each part of the deciduous codebase*
- [x] **Set up domain-specific subagents**
- Each domain gets a specialized agent with focused context and tools
- Agents can work in parallel on different parts of the codebase
- Reduces context overhead by scoping to relevant files/patterns
- **Implemented**: `.claude/agents.toml` with 6 domain agents
- **Integrated**: CLAUDE.md references agents, `deciduous init --claude` creates template
- [x] **Rust Core Agent** (`src/`)
- CLI commands, database layer, export/sync logic
- Diesel ORM, SQLite, command dispatch
- Focus: `src/main.rs`, `src/db.rs`, `src/lib.rs`, `src/serve.rs`
- [x] **Web Viewer Agent** (`web/`)
- React + TypeScript + D3/Dagre
- Components, hooks, views, styling
- Focus: `web/src/views/`, `web/src/components/`, `web/src/hooks/`
- [x] **Tooling/Templates Agent** (`.claude/`, `CLAUDE.md`)
- Claude Code slash commands and configuration
- Template sync with `src/init/`
- Focus: `.claude/commands/`, `CLAUDE.md`
- [x] **Documentation Agent** (`docs/`, `README.md`, `ROADMAP.md`)
- User-facing docs, guides, roadmap management
- GitHub Pages content
- Focus: `docs/`, `README.md`, `ROADMAP.md`, `CHANGELOG.md`
- [x] **CI/CD Agent** (`scripts/`, `.github/`)
- Build scripts, GitHub Actions, release automation
- Pre-commit hooks, validation
- Focus: `scripts/`, `.github/workflows/`, `Cargo.toml`
- [x] **Fix `/context` command name collision** (renamed to `/recover`)
- Renamed `.claude/commands/context.md` to `recover.md`
- Updated CLAUDE.md, README.md, and tooling docs
### Narrative User Guide
*A real, end-to-end tutorial that walks through an actual use case*
- [ ] **Narrative-driven tutorial** (like the jj tutorial)
- Not a reference manual—a story
- Follow a real feature from inception to merged PR
- Show the decision graph evolving alongside the code
- Include the missteps, dead ends, and course corrections
- [ ] **Cover the full workflow live**
- Start with `deciduous init` in a fresh project
- Log goals, make decisions, reject options, implement actions
- Show context recovery after a simulated "session break"
- Generate PR writeup from the graph
- Deploy to GitHub Pages
- [ ] **Dual perspective: human and AI**
- Show the human developer using the web viewer to review decisions
- Show the AI querying the graph to recover context
- Demonstrate handoff between sessions
- [ ] **Publish as a dedicated guide**
- Standalone page on the GH Pages site
- Could also be an asciinema + written hybrid
- Link prominently from README
### Real OSS Project Demo - Bootstrap from History
*Show how to add deciduous to an existing project and build decision history from what already exists*
- [ ] **Demo: Add deciduous to a real open source project**
- Pick a well-known OSS repo (maybe a Rust project for dogfooding)
- Initialize deciduous and build a decision graph from scratch
- Document the process as a replicable guide
- [ ] **Import decision history from git commits**
- Parse commit messages for decision-related keywords
- Auto-generate goal/action/outcome nodes from commit patterns
- Link nodes to commits automatically
- `deciduous import git --since "6 months ago"` or similar
- Heuristics: "feat:" → goal, "fix:" → action+outcome, "refactor:" → decision
- [ ] **Import decision history from PRs**
- Fetch PR titles, descriptions, and comments via GitHub API
- Extract goals from PR titles/descriptions
- Extract decisions from PR discussions and review comments
- Link PRs to generated nodes
- `deciduous import github-prs --repo owner/repo --since "2024-01-01"`
- [ ] **Import from GitHub Issues**
- Issues often capture goals and decisions
- Parse issue labels (bug, feature, enhancement) to determine node types
- Link closed issues to outcome nodes
- `deciduous import github-issues --repo owner/repo`
- [ ] **Interactive bootstrap wizard**
- `deciduous bootstrap` command for guided setup
- Walk through recent commits/PRs and ask user to categorize
- "This commit looks like a feature - create a goal node? [Y/n]"
- Build initial graph interactively with human validation
- Option for fully automatic mode with sensible defaults
- [ ] **Publish case study**
- Write up the experience of adding deciduous to an existing project
- Show before/after: navigating codebase without vs with decision graph
- Include screenshots of web viewer exploring imported history
- Highlight insights discovered from visualizing historical decisions
### Automated Graph Sync Workflow
*Multi-user state management should be seamless*
- [ ] **Default to diff/patch workflow for multi-user state management**
- With multiple users coming, graph database sync should be automated by the AI
- AI should automatically export patches when committing decision-related work
- AI should automatically apply patches when pulling/syncing
- Remove the manual friction of remembering to export/apply
- [ ] **Auto-export on commit**
- Before any commit that touched decision-related code, auto-run `deciduous diff export`
- Use branch-specific patch files (e.g., `.deciduous/patches/$(whoami)-$(branch).json`)
- Include patch file in the commit automatically
- [ ] **Auto-apply on pull**
- After `git pull`, detect new `.deciduous/patches/*.json` files
- Automatically apply them (idempotent - safe to re-apply)
- Report: "Applied 3 patches from teammates: alice-feature.json, bob-fix.json, carol-refactor.json"
- [ ] **Git hooks for automation**
- `post-commit` hook: auto-export current branch's decisions
- `post-merge` hook: auto-apply any new patches
- `pre-push` hook: ensure graph is synced and patches are committed
- [ ] **Claude Code workflow updates**
- Update tooling templates to include auto-sync behavior
- AI should do this automatically, not wait for user to ask
- "Before pushing, I'll sync the decision graph..." should be default behavior
- [ ] **Conflict resolution**
- When patches have conflicting nodes, use change_id to merge intelligently
- Prefer latest timestamp when edges conflict
- Interactive resolution mode if needed: `deciduous diff resolve`
### GitHub Pages Site Fixes
*Get the hosted web viewer working properly*
- [ ] Get GH Pages to not require CLI / configure auth for static hosting
- [ ] Get parity between GitHub Pages site and local React app
- [ ] Make sure all this builds and works + is tested manually for real workflows
- [ ] **Fix GH Pages showing stale graph data** - local DB has all nodes but docs/graph-data.json isn't synced/pushed; need automated workflow to keep GH Pages current
### Context Recovery (Critical)
*Make compaction restore actually work reliably*
- [ ] `/recover` command fully restores working state after context loss
- [ ] Query decision graph for recent goals, decisions, actions in progress
- [ ] **Sort nodes by recency** - most recently updated nodes first
- Use `updated_at` timestamp for sorting
- Show N most recent chains (like web viewer DAG view recency filtering)
- Recent activity is most relevant for context recovery
- [ ] Show what was being worked on, what's complete, what's pending
- [ ] Include recent git activity, uncommitted changes, branch state
- [ ] Pull in relevant prompts from history if available
- [ ] Goal: new session can pick up exactly where the last one left off
### Story View Componentization
*Transform the Story page into a reusable, structured narrative layer over decision graphs*
- [ ] **Componentize Story page elements**
- Break down Story page into discrete, reusable components
- Each section (timeline events, milestones, narrative blocks) becomes a component
- Components should be independently renderable and composable
- [ ] **Define Story data contract/schema**
- Create a well-defined JSON/TypeScript schema for Story structure
- Include: timeline events, milestones, phases, narrative blocks, metadata
- Schema should be versioned and extensible
- Consider compatibility with external systems (portable format)
- [ ] **Rich context over decision nodes/edges**
- Allow Story components to be attached to decision graph nodes as batches
- Stories become a higher-level narrative layer over the raw decision graph
- Link Story sections to specific goals, decisions, and outcomes
- Enable querying: "Show me the story for goal #42"
- [ ] **Story as documented institutional memory**
- Stories capture the "why" and context that raw nodes miss
- Can be used for onboarding, PR descriptions, release notes
- Export stories as standalone narratives or embed in docs
- [ ] **Portable format for external use**
- Story format should work beyond deciduous (potential export targets)
- Consider: Markdown export, JSON API, embed in other tools
- Keep schema simple enough to map to other narrative systems
---
## Backlog - Core Features
### Commit-Centric Graph Navigation
- [ ] More robust per-commit tooling
- Link nodes to commits more reliably
- Auto-detect commit context when logging actions/outcomes
- `deciduous add action "..." --commit HEAD` should be the default flow
- [ ] Commit-centric browsing in the web viewer
- Browse graph starting from commits (not just nodes)
- Show which nodes are associated with each commit
- Timeline view organized by commit history
- Click a commit → see the decision subgraph around it
- [ ] `deciduous log` command to show commits with their linked nodes
- [ ] Integration with `git log` to annotate commits with decision context
### Web Viewer - URL State & Sharing (Completed - PR #105)
- [x] **Query param encoding for shareable state**
- Encode ALL view parameters in URL query string
- Branch filter, selected node, view type, expanded chains, etc.
- Copy URL → share with teammate → they see exact same view
- Support deep linking to specific nodes: `?node=42&branch=feature-x`
- Persist state across page refreshes
- "Copy link" button in UI for easy sharing
### Web Viewer - DAG + Timeline Split View
- [ ] **Split view showing DAG and Timeline together**
- DAG view on one side, Timeline on the other
- Selecting a node group in DAG highlights corresponding timeline entries
- Swap panels in/out - view decision flow and log simultaneously
- Useful for reviewing decision history while seeing structure
- Configurable split direction (horizontal/vertical)
### Web Viewer - PR Integration
- [ ] **Link PRs to branch-filtered decision graph views**
- Click a PR link → opens deciduous web viewer filtered to that branch's nodes
- URL format: `deciduous.site/graph?branch=feature-foo` or similar
- PR description can embed a link that auto-filters the DAG to just that branch
- Users can explore the decision reasoning alongside the PR diff
- Integrate with GitHub PR template to auto-include graph link
- [ ] **GitHub App / Action for PR annotations**
- Automatically comment on PRs with link to branch-filtered graph
- Badge showing number of decision nodes in the branch
- One-click navigation from PR → decision graph explorer
- [x] **DAG recency filtering** (December 2025)
- Default view shows only 4 most recently active goal chains
- Chains sorted by most recent node update time within the chain
- "Show more" and "Show all" controls to expand view
- Rust utility functions (`build_chains`, `sort_chains_by_recency`, `get_recent_chains`)
### Code Tracking & File Associations (Extended)
- [ ] **Web UI: "View Code" button on nodes**
- Click a node → see associated files
- Show git diff for the commit linked to that node
- Quick navigation to file locations
- [ ] Update `.claude/commands/` templates
- Include instructions to log file associations
- `deciduous add action "..." --files <changed-files>`
- [ ] `deciduous files <node-id>` command to list associated files
- [ ] Reverse lookup: `deciduous nodes --file src/foo.rs` to find nodes touching a file
- [ ] **Enforce file linking**
- Remind/warn when creating action nodes without `--files`
- Hook integration: auto-detect staged files when logging actions
- Template instructions emphasizing file association importance
- "You modified 5 files but didn't link any to this node" warnings
- [ ] **`deciduous audit --associate-files`** (like `--associate-commits`)
- Retroactively link files to nodes based on:
- Commit associations (node has commit → get files from that commit)
- Time correlation (files changed near node creation time)
- Title/description keyword matching (node mentions "auth" → find auth files)
- Interactive mode: show node + candidate files, let user confirm
- Batch mode: auto-associate from linked commits (high confidence)
- `--dry-run` to preview associations
- [ ] **File coverage report**
- `deciduous audit --file-coverage`
- Show which files have decision graph coverage
- Identify "dark spots" - frequently changed files with no linked nodes
- Help ensure important code has documented reasoning
### Prompt Tracking (Extended)
- [x] **View prompts in web UI**
- Display the original prompt in node detail panel
- [ ] Prompt history view in web UI
- See what prompt led to each decision chain
- Search/filter by prompt content
- [ ] Prompt templates
- Save effective prompts for reuse
- Share prompt patterns that lead to good decision trees
- [ ] Prompt → Outcome analysis
- Correlate prompt patterns with successful outcomes
- Identify which prompt styles lead to better decisions
- [ ] **Extended prompt features in web UI**
- Filter/search nodes by prompt content
- "Copy prompt" button for reuse
---
## Backlog - Tooling & Automation
### Installation & PATH Handling
*Graceful handling of common installation issues*
- [ ] **Detect and suggest PATH fixes for `~/.cargo/bin`**
- After `cargo install deciduous`, binary is in `~/.cargo/bin`
- Many users don't have this in PATH
- Detect when `deciduous` command fails due to PATH issues
- Provide clear instructions for adding to PATH:
- bash/zsh: `export PATH="$HOME/.cargo/bin:$PATH"` in `.bashrc`/`.zshrc`
- fish: `set -gx PATH $HOME/.cargo/bin $PATH` in `config.fish`
- Consider: post-install script that checks and warns
- Consider: `cargo install` wrapper that checks PATH after install
- [ ] **Graceful error messages for common issues**
- "command not found: deciduous" → suggest PATH fix
- Database not found → suggest `deciduous init`
- Permission errors → suggest fix
- Missing dependencies (graphviz for --png) → suggest install command
### Release Tooling
- [ ] **Automated release notes generation**
- `deciduous release-notes --from v0.7.0 --to v0.8.0`
- Query graph for all goals/outcomes between versions
- Group by feature area (web viewer, sync, export, etc.)
- Generate markdown summary of what changed and why
- [ ] **PR tagging for releases**
- Tag PRs that landed in a release
- `deciduous release tag-prs v0.8.0` - adds label to all PRs in release
- Link PRs back to decision graph nodes
- [ ] **Release summary from decision graph**
- Walk the graph to find all completed goals since last release
- Show the decision chain that led to each feature
- Include key prompts/feedback that drove changes
- Generate changelog with decision context
- [ ] **GitHub Actions CI/CD for releases**
- Automate the entire release pipeline via GitHub Actions
- Trigger: push tag matching `v*` pattern (e.g., `v0.9.0`)
- Pipeline steps:
1. Run `cargo test` and `cargo clippy`
2. Build release binaries for multiple platforms (linux, macos, windows)
3. Create GitHub Release with auto-generated notes
4. Publish to crates.io (`cargo publish`)
5. Upload platform binaries as release assets
- Workflow file: `.github/workflows/release.yml`
- Optional: Separate workflow for nightly/canary builds
- Consider: cargo-dist or release-plz for Rust-specific release automation
- [ ] **Pre-built binary distribution for all platforms**
- Build and distribute pre-compiled binaries so users don't need Rust/cargo
- **Target platforms:**
- Linux x86_64 (glibc and musl for maximum compatibility)
- Linux aarch64 (ARM64 for Raspberry Pi, cloud instances)
- macOS x86_64 (Intel Macs)
- macOS aarch64 (Apple Silicon M1/M2/M3)
- Windows x86_64 (.exe)
- **Distribution channels:**
- GitHub Releases with platform-specific tarballs/zips
- Install script: `curl -fsSL https://deciduous.dev/install.sh | sh`
- Homebrew tap for macOS: `brew install deciduous/tap/deciduous`
- Consider: Chocolatey for Windows, apt/yum repos for Linux
- **Binary naming convention:** `deciduous-{version}-{os}-{arch}.{ext}`
- **Verification:** SHA256 checksums and optional GPG signatures
- **Self-update:** `deciduous update` to fetch latest binary for current platform
- [ ] **Release checklist automation**
- `deciduous release prep v0.9.0` - prepare release locally
- Bump version in Cargo.toml
- Update CHANGELOG (if exists)
- Run tests and clippy
- Generate release notes from decision graph
- `deciduous release publish v0.9.0` - trigger the release
- Create and push git tag
- GitHub Actions takes over from there
- Fail-safes: block release if tests fail or graph has incomplete goals
### Roadmap Manager Tool
- [ ] **Link roadmap items to work**
- Roadmap items should link to decision graph nodes
- Track progress through the graph (goal -> decisions -> outcomes)
- Show completion status based on linked outcomes
- [ ] **Work item integration** (future)
- Design with external ticketing in mind (JIRA, Linear, GitHub Issues)
- Roadmap items could link to external tickets
- Sync status bidirectionally
- Keep this extensible for enterprise workflows
- [ ] **CLI commands**
- `deciduous roadmap list` - show roadmap items and their status
- `deciduous roadmap link <item> <node-id>` - link to graph node
- `deciduous roadmap status` - show completion based on linked nodes
### Claude Code Hooks Integration
- [ ] Explore using Claude Code hooks to guarantee workflow behavior
- Claude Code supports hooks that run on various events (tool calls, messages, etc.)
- Could enforce decision graph logging more reliably than instructions alone
- [ ] **Pre-tool hooks**: Before file edits
- Auto-log `action` node when Claude is about to modify files
- Capture which files are being changed
- Block edits if no active goal exists in the graph
- [ ] **Post-tool hooks**: After successful operations
- Auto-log `outcome` nodes after code changes succeed
- Auto-link outcomes to their parent actions
- Trigger `deciduous sync` after significant changes
- [ ] **Pre-commit hooks**: Before git commits
- Verify graph integrity (no orphan outcomes/actions)
- Require at least one goal node for the current session
- Auto-add commit hash to recent action/outcome nodes
- [ ] **Session start hooks**: On conversation begin
- Auto-run `/recover` equivalent
- Load graph state and surface pending decisions
- Warn if there are disconnected nodes needing attention
- [ ] **Prompt submit hooks**: When user sends a message
- Detect feature requests and auto-create goal nodes
- Capture original prompt in node metadata
- [ ] Hook configuration in `.deciduous/hooks.toml`
- Enable/disable specific hooks
- Configure strictness (warn vs block)
- Custom hook scripts for project-specific needs
- [ ] Document hook setup in Claude Code settings
- Integration guide for `.claude/settings.json`
- Example hook configurations for different workflow styles
### Claude Code Memories Integration
- [ ] **Leverage Claude Code memories**
- Claude Code has "memories" features that persist across sessions
- Could store decision graph summaries, recent goals, key patterns
- Auto-populate memories with recent decision context
- Memories could include: current goals, pending decisions, recent outcomes
- [ ] **Claude Code memories**
- Detect and update `.claude/memories/` or equivalent
- Store project-specific decision patterns
- "Last session worked on goal #X, consider continuing"
- [ ] **Memory-graph sync**
- `deciduous memories export` - export decision summaries to memory format
- `deciduous memories update` - update Claude Code memories with recent decisions
- Bidirectional: memories inform context recovery
### Roadmap Skill Integration
- [ ] **Claude Code skill for roadmap management**
- `/roadmap` skill to interact with ROADMAP.md and decision graph
- Show current roadmap items, their status, linked nodes
- Add/update roadmap items with decision graph links
- [ ] **Roadmap-graph bidirectional links**
- Roadmap items can reference graph nodes by ID
- Graph nodes can link back to roadmap items
- Track completion: roadmap item is "done" when linked outcome exists
### Retroactive Commit Association
- [ ] **Audit existing nodes and associate with git commits**
- Many early nodes were created without `--commit` flag
- Cross-reference node `created_at` timestamps with `git log` dates
- Match node titles/descriptions to commit messages
- `deciduous audit --associate-commits` command to suggest matches
- Interactive mode: show node + candidate commits, let user confirm
- Batch mode: auto-associate high-confidence matches (>90% title similarity)
- [ ] **Backfill script for existing graphs**
- One-time migration to enrich old nodes with commit data
- Parse commit messages for keywords matching node titles
- Use time windows (node created within N minutes of commit)
- Generate report of associations made
- [ ] **Ongoing commit detection**
- When running `deciduous sync`, detect recent commits without linked nodes
- Suggest: "Found 3 commits with no linked decisions - want to associate them?"
- Help maintain commit-node linkage going forward
### Git Integration & Pre-commit Hook Awareness
- [ ] Inspect and respect pre-commit hooks
- Detect `.git/hooks/pre-commit` or `.husky/` hooks
- Parse hook contents to understand what checks run
- Warn users if hooks might reject commits (linting, formatting, tests)
- [ ] Pre-flight commit validation
- `deciduous commit --dry-run` to simulate what hooks would do
- Show which checks would pass/fail before actual commit
- [ ] Auto-fix integration
- If hooks run formatters (prettier, rustfmt), detect and apply fixes
- Re-stage auto-fixed files before commit
- [ ] Hook-aware templates
- Update `.claude/commands/` to mention pre-commit awareness
- Instruct Claude to check for hooks before committing
### Git.log File Reliability
- [ ] Investigate why git.log file isn't always being created/updated
- User reported missing git.log during session
- This file should always exist and track all git commands run
- [ ] Ensure git.log is created on `deciduous init`
- [ ] Add git.log writing to all git-related operations
- [ ] Consider moving git.log into `.deciduous/` directory for better organization
- [ ] Add `deciduous log` command to view git.log contents
- [ ] Document git.log purpose and location in tooling files
### Template Sync (init/ ↔ actual files)
- [x] **FIX: `deciduous update` destroys custom content in command files** (v0.8.2)
- ~~Currently `update` overwrites `.claude/commands/*.md` completely~~
- ~~This destroys all custom instructions users have added~~
- Fixed: init templates now match actual files
- [ ] **Auto-detect when tooling files are out of sync**
- When `.claude/commands/*.md` or `CLAUDE.md` are modified
- Remind/enforce updating corresponding templates in `src/init/templates.rs`
- The templates should match what's in the actual files
- [ ] **Validation command**
- `deciduous validate-templates` - check if templates match actual files
- Warn if they've diverged
- Optionally auto-update templates from actual files
- [ ] **Memory/hook for sync**
- Add to Claude Code memories: "If you modify .claude/commands or CLAUDE.md, also update src/init/templates.rs"
- Could be a pre-commit check or a deciduous hook
- [ ] **FULLY AUTOMATE template sync** (Critical)
- **Goal: Never manually sync templates again**
- Build script or CI step that extracts actual file contents into templates.rs
- Single source of truth: the actual `.claude/` and `CLAUDE.md` files
- `src/init/templates.rs` constants are auto-generated from these files
- Options:
- `build.rs` script that reads files and generates template constants
- Pre-commit hook that regenerates templates section
- CI check that fails if templates don't match actual files
- Include ALL tooling files:
- `.claude/commands/decision.md`
- `.claude/commands/recover.md`
- `CLAUDE.md`
- Never have drift between what `deciduous init` creates and what the repo actually uses
---
## Backlog - Architecture & Quality
### Documentation Restructure
- [ ] Rethink the `docs/` folder organization
- Currently: GitHub Pages viewer lives here
- Problem: Also contains ad-hoc design docs (like MULTI_USER_SYNC.md)
- Consider: Separate `docs/` (user-facing) from `design/` (internal design docs)
- Consider: Move viewer to dedicated folder
- [ ] Consolidate documentation
- Single source of truth in CLAUDE.md (the canonical reference)
- .claude/commands/ derives from CLAUDE.md patterns
- README.md stays user-facing (installation, quick start)
- [ ] Auto-generate tooling docs
- `deciduous docs` command to output markdown documentation
- Include all commands, options, examples
- Keep README.md and tooling files in sync automatically
---
## Backlog - Future Vision
### LLM Critique & Analysis
- [ ] `deciduous critique --goal <id>` - Have an LLM analyze a goal's decision chain
- Review decisions made, options chosen/rejected
- Identify potential blind spots or unconsidered alternatives
- Evaluate confidence levels vs actual outcomes
- Suggest improvements for future similar decisions
- [ ] Multi-model critique comparison
- `deciduous critique --goal <id> --models claude,gpt4,gemini`
- See how different models evaluate the same decision chain
- Highlight where models agree/disagree on quality
- [ ] Critique storage - save critiques as special nodes linked to goals
### LLM Benchmarking Framework
- [ ] **Goal-based benchmarking**: Use the same goal/task across multiple LLMs
- Define a goal with acceptance criteria
- Run each model on the same task
- Compare: decisions made, paths taken, outcomes achieved
- [ ] `deciduous benchmark` command
- `deciduous benchmark --task "Implement feature X" --models claude,gpt4,gemini,llama`
- Each model gets isolated graph namespace
- Automated or human evaluation of outcomes
- [ ] Metrics to capture:
- Decision quality (did they consider good options?)
- Path efficiency (how direct was the route to outcome?)
- Confidence calibration (were high-confidence decisions correct?)
- Recovery ability (how did they handle setbacks?)
- Graph structure (complexity, dead ends, backtracking)
- [ ] Benchmark reports
- Side-by-side comparison of decision graphs
- Aggregate stats across multiple benchmark runs
- Export to shareable format for publishing results
- [ ] Reproducible benchmark suites
- Define standard tasks with known-good solutions
- Version-controlled benchmark definitions
- CI integration for regression testing model capabilities
### DuckDB for OLAP Analytics
- [ ] Add DuckDB as optional analytical backend for decision graph queries
- SQLite is great for OLTP (single-project, real-time logging)
- DuckDB excels at OLAP (cross-project analytics, time-series queries, aggregations)
- [ ] Use cases for analytical queries:
- **Cross-project patterns**: "What decision patterns lead to successful outcomes across all my projects?"
- **Time-series analysis**: "How has my decision-making evolved over the past 6 months?"
- **Confidence calibration**: "Are my high-confidence decisions actually more successful?"
- **Path analysis**: "What's the average depth of decision trees that lead to good outcomes?"
- **Bottleneck detection**: "Which decision types take longest to resolve?"
- [ ] Implementation ideas:
- Export SQLite graphs to Parquet files for DuckDB ingestion
- `deciduous export --parquet` for analytical snapshots
- `deciduous analytics` subcommand for running OLAP queries
- Optional: federated queries across multiple project databases
- [ ] Potential analytical views:
- Decision funnel analysis (goal → option → decision → action → outcome conversion)
- Confidence vs outcome correlation matrix
- Branch/feature complexity metrics
- Session productivity heatmaps
- Node type distribution over time
- [ ] Visualization integration:
- Export to formats compatible with BI tools (Metabase, Superset, etc.)
- Built-in charts in web viewer
- `deciduous report` to generate analytical summaries
---
### Live Graph Diff Viewer
- [ ] **Real-time graph following**
- Diff viewer that "follows" the decision graph as nodes are written
- User sees live updates as AI creates/modifies nodes
- Stream-style view of graph changes in real-time
- Could use websocket or file watching to detect changes
- Web mode: push updates via SSE or websocket
- [ ] **Visualization of graph deltas**
- Show what nodes/edges were added, modified, deleted
- Highlight new nodes with a visual indicator
- Animate transitions between graph states
- Timeline scrubber to replay graph evolution
- [ ] **Integration with editor workflows**
- Side panel in IDE showing live graph updates
- Works alongside Claude Code
- Non-blocking: viewer runs in separate process/terminal
### Live Graph Editor (Experimental)
- [ ] **Bidirectional graph editing**
- Not just viewing - actually edit the graph live
- Add/modify/delete nodes through the viewer UI
- Changes sync back to SQLite database
- Potentially coordinate edits with running AI session
- [ ] **Collaborative editing**
- Multiple users can edit graph simultaneously
- Operational transform or CRDT for conflict resolution
- Real-time cursor presence (see where others are editing)
- This is ambitious but could enable pair programming with AI
- [ ] **Graph manipulation tools**
- Drag and drop nodes to reorganize
- Quick actions: merge nodes, split nodes, reparent
- Undo/redo support
- Validation: prevent invalid graph structures
---
### Claude Desktop Integration
- [ ] **MCP server for Claude Desktop**
- Expose deciduous as an MCP (Model Context Protocol) server
- Allow Claude Desktop users to interact with decision graphs
- Not everyone uses CLI or Claude Code - meet users where they are
- [ ] **Consider ACP (Agent Client Protocol) integration**
- [Symposium ACP SDK](https://github.com/symposium-dev/symposium-acp) - Rust SDK for ACP
- ACP standardizes agent-client communication (complementary to MCP)
- Potential integration approaches:
- **Proxy component**: Intercept agent communications, auto-log decisions
- **Base agent**: Implement deciduous as an ACP-compliant agent
- **Conductor integration**: Decision graph as middleware in proxy chains
- Benefits:
- Automatic decision capture without manual logging
- Works with any ACP-compatible editor/agent
- Composable architecture - add/remove decision tracking dynamically
- [ ] **Core MCP tools**
- `add_node` - create goal/decision/action/outcome/observation nodes
- `link_nodes` - connect nodes with edges
- `query_graph` - search and filter the decision graph
- `get_context` - retrieve recent decisions for context recovery
- `sync_graph` - export/import for sharing
- [ ] **Desktop-friendly workflows**
- Decision tracking for non-coding tasks (writing, research, planning)
- Project management and task breakdown
- Meeting notes → decision nodes conversion
- General knowledge work, not just software engineering
- [ ] **Cross-platform graph access**
- Same `.deciduous/` database works from CLI, web, and Desktop
- Claude Desktop can read graphs created by Claude Code and vice versa
- Unified decision history across all interaction modes
- [ ] **Resource exposure**
- Expose graph data as MCP resources
- Recent nodes, active goals, pending decisions as browsable resources
- Graph statistics and health metrics
- [ ] **Prompt support**
- MCP prompts for common workflows
- "Start new goal", "Review decisions", "Context recovery"
- Guided decision-making templates
---
### Historical Linkages - Documents as Graph Citizens
*External artifacts become first-class nodes in the decision graph, not just metadata*
This goes beyond simple integrations - documents, release notes, tags, PR bodies, and conversations become **part of the real graph and metadata model**.
- [ ] **Document nodes**
- New node types: `document`, `release`, `conversation`, `pr_body`
- Documents link to decision nodes they reference
- Bidirectional: decisions can cite documents, documents can embed decision context
- Full-text search across document content
- Version tracking for document evolution
- [ ] **Release notes as graph nodes**
- Each release becomes a node linked to its constituent goals/outcomes
- `deciduous release create v0.9.0` - auto-generates release node
- Release node has edges to all completed goals since last release
- Queryable: "What decisions led to v0.8.0?" → traverse the graph
- Release changelogs derived from graph traversal, not manual writing
- [ ] **Git tags as graph anchors**
- Tags sync to the graph automatically
- `v0.8.12` tag creates a snapshot node capturing graph state at that point
- Time-travel: view graph as it existed at any tagged version
- Diff tags: "What changed in the graph between v0.8.0 and v0.9.0?"
- [ ] **PR bodies integrated into graph**
- PR description becomes a document node linked to branch's decisions
- PR comments can reference graph nodes: "This implements decision #42"
- Auto-populate PR template with links to relevant decision nodes
- Review comments link back to graph for context
- Merged PR triggers outcome nodes automatically
- [ ] **Conversation threads as decision context**
- Chat/discussion threads can be attached to decisions
- "Why did we choose X?" → link to the Slack/Discord/GitHub discussion
- Conversation summaries as nodes (AI-generated or manual)
- Preserve the human context that influenced decisions
- Search discussions by linked decision nodes
- [ ] **Writeups and design docs**
- RFC/ADR documents become graph nodes
- Design doc links to the decisions it proposes
- Implementation decisions link back to the design doc
- Track drift: "Design said X, but we implemented Y because..."
- `deciduous writeup` output becomes a linkable document node
- [ ] **Cross-repository linkages**
- Link decisions across different projects/repos
- "Phoenix Framework decision #123 influenced our decision #456"
- External project graphs can be referenced (read-only links)
- Useful for documenting dependencies on upstream choices
- Federation: query across multiple project graphs
- [ ] **Query the extended graph**
- `deciduous query "show all PRs related to goal #42"`
- `deciduous query "what conversations mentioned auth decisions?"`
- `deciduous query "release notes that cite this outcome"`
- Graph traversal includes document nodes seamlessly
- Filter by document type, date range, author
- [ ] **Import/export document linkages**
- Export decision graph with all linked documents
- Import external documentation into the graph
- Markdown files can declare graph links in frontmatter
- `deciduous import-docs ./docs/*.md` - scan for decision references
---
## Future Enhancements
- [ ] Consider support for additional editors in the future (Cursor, Copilot, etc.)