Step 1 of 6 — Board View
Step 1: Starting point — Board View. User sees the Vision Tracker board. They spot "Vision Tracker Design" in the In Progress column and want to review its decisions. user clicks the card
Planned
task
Migrate vision-state schema
idea
Breadcrumb-to-tracker bridge
task
Build drill-down component
In Progress
spec
Vision Tracker Design ←
task
Light mode color fix
Complete
decision
D3: New entity types
spec
Product realignment
Step 2: Drill-down into the spec. Board replaced by detail view. Breadcrumb shows "Board > Tracker Design". Slots appear: linked doc, 9 decisions (with Approve/Discuss/Decline), connected items (collapsed), evidence (collapsed).
Board › Vision Tracker Design
spec design Vision Tracker as Primary Roadmap in progress
› Linked Document product-realignment.md
Option A: ROADMAP.md only — Agent reads/writes natural language. No impedance mismatch.
Option B: Vision Tracker only — Queryable, filterable, interactive, visual dependency graphs.
Option C: Both, kept in sync — Manual sync will fail. Two sources of truth means zero.
Option D: Tracker primary, markdown generated — Single source of truth. Git-diffable snapshots on demand.
The key insight: if the tracker is the agent's work queue, the agent has self-interest in keeping it current.
› Decisions 9
D1: Tracker is primary, markdown generated
D2: New fields — priority, effort, planLink
D3: New entity types — feature, initiative
D4: Typed edges user clicks D4 row
+ 5 more...
› Connected Items 3 2 tasks, 1 spec
› Evidence 0
Step 3: D4 expands inline. Clicking the decision row reveals its rationale, pros/cons right below it — no navigation needed. User reads the context, then decides: Approve, Discuss, or Decline. user clicks Discuss
Board › Vision Tracker Design
spec design Vision Tracker as Primary Roadmap in progress
› Decisions 9
D1: Tracker is primary, markdown generated
D2: New fields — priority, effort, planLink
D3: New entity types — feature, initiative
D4: Typed edges — blocks, informs, implements, supports
Rationale: Every connection between items needs a semantic type to drive UI behavior and dependency logic. Without typed edges, all connections are generic — the graph can't distinguish "this blocks that" from "this informs that."

Pros

  • Enables dependency-aware scheduling
  • Graph renders different edge styles per type
  • Supports the informs deliberation pattern
  • Fixed set keeps complexity bounded

Cons

  • Fixed types may not cover all future needs
  • More complex than generic connections
  • Migration required for existing edges
+ 5 more...
Step 3: Discuss D4. A discussion drawer slides open from the right, scoped to this decision. User can comment before deciding. The drill-down dims behind it.
Board › Vision Tracker Design
spec Vision Tracker as Primary Roadmap
Decisions (9) — D4 selected
D4: Typed Edges ✕ Close
DISCUSSION
No comments yet.
Start a discussion about this decision.
user clicks Approve
Step 4: D4 approved. Drawer closes. Decision list updates — D4 now shows "✓ Approved" with reduced opacity. User clicks D4's row to drill deeper into its details. user clicks D4 row
Board › Vision Tracker Design
spec Vision Tracker as Primary Roadmap in progress
› Decisions 9 2 approved
D1: Tracker is primary
D2: New fields
D3: New entity types
D4: Typed edges ←
+ 5 more...
Step 5: Drilled into D4. Breadcrumb grows: Board › Tracker Design › D4. Same slot pattern applied recursively — D4 has its own linked doc, connected tasks, and evidence. Every item is drillable to any depth. user clicks "Board" in breadcrumb
Board › Vision Tracker Design › D4: Typed Edges
decision design D4: Typed edges — blocks, informs, implements, supports complete
› Linked Document product-realignment.md §edges
Every connection carries a semantic type: blocks (hard dependency), informs (deliberation), implements (concrete realization), supports (evidence/backing).
› Connected Items 2
Implement edge type validation implements ›
Graph rendering for typed edges implements ›
› Evidence 1 1 design doc
Step 6: Back to board. User clicked "Board" in breadcrumb — jumps straight back. D4 now appears in the Complete column. The entire flow: click card → review decisions → discuss → approve → drill deeper → jump back.
Planned
task
Migrate vision-state schema
idea
Breadcrumb-to-tracker bridge
task
Build drill-down component
In Progress
spec
Vision Tracker Design
task
Light mode color fix
Complete
decision
D3: New entity types
decision
D4: Typed edges ✓
spec
Product realignment