veritas-kanban/docs/design-parallel-visualization.md

Design: Parallel Work Stream Visualization

Status: Design Draft GitHub Issue: #43 Priority: Medium

Overview

Add a timeline/swimlane view to visualize parallel task execution, showing which tasks ran concurrently, how long each took, and where bottlenecks occurred.

Use Cases

1. Multi-agent sprint review — After spawning 12 parallel agents, see which completed first, where time was spent
2. Bottleneck detection — Identify tasks that blocked others or took unexpectedly long
3. Capacity planning — Understand actual parallelism achieved vs theoretical max
4. Sprint retrospective — Visualize sprint execution for process improvement

Proposed Architecture

Data Model

The timeline view will use existing data:

• task.timeTracking.entries[] — Start/end times per task
• task.status — Current state
• task.agent — Assigned agent
• activity-log.json — Status change timestamps

New fields (optional):

• task.parallelismGroup — Group related parallel tasks
• task.dependsOn[] — Explicit dependencies for visualization

API Endpoints

// Timeline data for a date range
GET /api/analytics/timeline
Query: { from: ISO, to: ISO, agent?: string, project?: string }
Response: {
  tasks: [{
    id: string,
    title: string,
    agent: string,
    segments: [{ start: ISO, end: ISO, status: string }]
  }],
  metrics: {
    parallelismFactor: number,
    throughput: number,
    avgLeadTime: number
  }
}

// Aggregate metrics for a sprint
GET /api/analytics/metrics
Query: { sprint?: string, from?: ISO, to?: ISO }
Response: {
  tasksCompleted: number,
  avgDuration: number,
  parallelismPeak: number,
  agentUtilization: Record<string, number>
}

UI Components

┌─────────────────────────────────────────────────────────────┐
│ [Kanban] [Timeline] [Dashboard]            🔍 Filter  📅    │
├─────────────────────────────────────────────────────────────┤
│ 2026-02-05                      8:00   9:00   10:00   11:00 │
├─────────────────────────────────────────────────────────────┤
│ veritas    │███████████████████████│                        │
│            │  REL-001              │                        │
├─────────────────────────────────────────────────────────────┤
│ codex-1    │     │█████│                                    │
│            │     │REL-2│                                    │
├─────────────────────────────────────────────────────────────┤
│ codex-2    │       │████████│                               │
│            │       │  REL-3 │                               │
├─────────────────────────────────────────────────────────────┤
│ codex-3    │         │██████████████│                       │
│            │         │    REL-4     │                       │
└─────────────────────────────────────────────────────────────┘

Components needed:

1. TimelinePage.tsx — New page at /timeline
2. TimelineChart.tsx — Gantt-style visualization (use @nivo/gantt or custom)
3. TimelineFilters.tsx — Date range, agent, project filters
4. ParallelismMetrics.tsx — Key metrics cards

Implementation Phases

Phase 1: Data Layer (2-3 hours)

• Add timeline API endpoint
• Aggregate time tracking data into segments
• Calculate parallelism metrics

Phase 2: Basic UI (4-6 hours)

• Create TimelinePage with navigation
• Implement basic Gantt chart (horizontal bars)
• Add date range picker

Phase 3: Polish (2-4 hours)

• Add swimlanes per agent
• Color-code by task type/status
• Zoom levels (hour/day/week)
• Hover tooltips with task details

Phase 4: Integration (2 hours)

• Link from task cards to timeline position
• Add to dashboard as widget option

Technical Decisions

Chart Library Options:

1. @nivo/gantt — React-native, good for static Gantt charts
2. react-gantt-schedule-timeline-calendar — Feature-rich but heavy
3. Custom with D3 — Maximum flexibility, more work
4. CSS Grid + custom — Simplest, good for MVP

Recommendation: Start with CSS Grid + custom for MVP, migrate to @nivo if needed.

Dependencies

• Existing time tracking data must be populated
• Status history service provides state change timestamps

Risks

1. Data gaps — Tasks without time tracking won't appear
2. Performance — Large date ranges with many tasks may be slow
3. Complexity — Full Gantt features (drag, resize, dependencies) add significant scope

Success Metrics

• Users can identify which tasks ran in parallel
• Average parallelism factor is visible
• Sprint retrospectives use the timeline view