Dependency Graph
The story dependency graph is an interactive visualization of your project's dependency structure — stories, PRDs, and releases — so you can see execution order, critical paths, and cross-PRD / cross-release relationships at a glance.
Accessing the Graph
The graph lives inside the Stories page as a view toggle (List / Graph). The old /graph URL redirects to /stories?view=graph so existing links keep working. It's also linked from the sidebar as Dependency Graph.
What's in the Graph
The graph shows three node types, powered by React Flow (@xyflow/react):
| Node | What it represents |
|---|---|
| Story | An individual story with status color, difficulty, and a checkpoint flag for quality_checkpoint stories |
| PRD | A PRD container grouping the stories it owns |
| Release | A release container grouping the PRDs assigned to it |
Edges are directed — an arrow from A to B means "A depends on B" (B must finish before A can start).
Visual Indicators
- Status colors on story nodes — pending, running, passed, merged, failed, skipped, etc.
- Quality-checkpoint flag — story nodes typed as
quality_checkpointare visually distinct (flag icon + dashed border) - Depth-based edge gradient — when you highlight a node, the ancestor chain is colored with a 25-color rainbow from yellow (closest ancestor) to cyan (deepest ancestor), so you can read depth at a glance
- Mini-map in the corner for navigating large graphs
Interaction
- Click a node — highlights its full ancestor chain with the depth rainbow so you can see exactly what it depends on
- Double-click a story node — opens the story detail modal
- Drag nodes — manually arrange the layout (switches you into a custom layout that auto-saves)
Layouts
The layout dropdown offers four auto-generated layouts plus any custom ones you've saved:
| Layout | Description |
|---|---|
| Horizontal | Left-to-right flow |
| Horizontal Compact | Tighter horizontal spacing |
| Vertical | Top-to-bottom flow |
| Vertical Compact | Tighter vertical spacing |
| Custom (saved) | Your manually arranged layouts, per-project |
Saving Custom Layouts
- Drag nodes to arrange the graph how you like
- Use Save in the toolbar to name and persist the layout
- Switch back to it any time from the layout dropdown
- Set default makes a saved layout the one that loads automatically
Deleting Custom Layouts
Pick a custom layout from the dropdown and use Delete layout to remove it. Auto-generated layouts can't be deleted.
Scope Filters (Toolbar)
Two stacked selectors at the top-left of the canvas scope what's drawn:
- Release scope —
All Releases/Unlinked PRDs/ each release by name - PRD scope —
All PRDs/ each PRD by sequence number + short title
"Unlinked PRDs" only appears when there are PRDs not yet attached to any release.
Settings Toggles
On the toolbar:
- Dead ends — show/hide stories with no dependents (leaf nodes). Hiding them can de-clutter busy graphs.
- External deps — show/hide cross-PRD dependency edges. Useful for trimming visual noise when you're focused on intra-PRD work.
Both toggles persist in user settings.
Cross-PRD Dependencies
Stories can depend on stories from other PRDs using the prdSeq:phase.epic.story format — for example 1:1.2.1 means "story 1.2.1 from PRD 1". The planning pipeline's Dependency Mapper writes these references; your edits can add or remove them. Enable the External deps toggle to render these cross-PRD edges.
Tips
- Use the graph to spot bottleneck stories — stories with many dependents sit on the critical path, so prioritizing or splitting them pays off most
- Quality checkpoints act as natural gates — everything downstream in the graph waits for them, so placement matters
- Compact layouts work better for large PRDs; start with
Horizontal Compactfor wide plans - Custom layouts persist across sessions, so arrange once and the graph stays how you left it
- Combine release + PRD scope filters to focus on just the stories you care about right now