Activity Dashboard 2.0 - Design Update

Date: November 27, 2025 Version: 2.0 Status: Final Design Package Meeting: Will-Hal Design Review

Executive Summary
Key Design Insights from Meeting
Design Philosophy
Documentation Package
Implementation Roadmap

Executive Summary

The Activity Dashboard 2.0 represents a fundamental shift from machinery metrics to journey navigation. Based on stakeholder analysis from the November 27, 2025 design review meeting with Will and Hal, this update transforms the dashboard from showing "how the engine works" to "where we're going and what's in the way."

Core Transformation

From Engine Diagnostics:

Message counts, session durations, token usage
"How is it doing it?"
Machinery-focused interface

To GPS Navigation:

Task progress, blocked features, route to completion
"What has it made?"
Journey-focused interface

Critical Quote from Stakeholder

"The gold isn't in how is it doing it... the real stuff is features, deliverables, targets reached. What you want is: How do I get from A to B? What are my obstacles? And what's my route?" — Will, Design Review Meeting, November 27, 2025

Key Design Insights

The dashboard should function like a car's GPS navigation system, not its engine diagnostics panel.

GPS Dashboard Elements:

Where am I? → Current task progress
Where going? → Project milestones
What route? → Task → Commit → Done
What obstacles? → Blocked tasks only

Not Shown (Engine Metrics):

RPM, fuel injection rate, engine temperature
Similarly: Message counts, session duration, token usage

2. Exception-Based Display

"If it's 40, 40, 40, 40, 40 every time, don't show it."

Rule: Only show deviations from baseline. Hide uniform data.

Metric	Baseline	Display Rule
QA Score	40 (passing)	Show only if ≠ 40
Task Status	Normal flow	Show only if blocked
Build Status	Success	Show only if failed

3. Task-Centric Architecture

Everything flows toward tasks as the primary entity:

TASK (Primary)
├── ☑ Checkbox (source of truth for completion)
├── Status (pending/in_progress/blocked/done)
├── Linked Sessions (evidence)
└── Linked Commits (evidence)

Sessions and commits are supporting evidence, not primary metrics.

4. Three-Level Information Hierarchy

LEVEL 1: Primary View (Non-scrolling - "actual information on a non-scrolling screen")
├── Portfolio summary (all projects)
├── Task Kanban (selected project)
├── 5 activity highlights
├── Blocked tasks panel
└── Work distribution chart

LEVEL 2: Drill-Down (On-demand)
├── Full task list with details
├── Commit timeline
├── Session summaries
└── Progress burndown

LEVEL 3: Deep Inspection (Hidden - "we can have it in the details")
├── Session message history
├── Commit diffs
├── Task change history
└── Raw activity logs

5. The 5-Second Test

Users must answer these questions in < 5 seconds without scrolling:

Which project needs attention?
What tasks are in progress?
What is blocking progress?
What completed recently?
Am I on track?

Design Philosophy

GPS Not Engine: What to Remove vs Keep

Remove from Primary View

Engine Metric	Why Remove
Message counts	"Nobody cares" - no actionable signal
Session duration	Shows process, not progress
Token usage	Engine internals
Word counts	Machinery metric
Uniform QA scores	Repeating data = no information
Version numbers	Unless different from expected

Keep in Primary View

Navigation Element	Why Keep
Task checkboxes	Source of truth for completion
Project progress bars	High-level position indicator
Blocked tasks	"Obstacles in the way"
Linked commits	Evidence of progress
Activity highlights (5 max)	Recent journey milestones
Kanban board	"Has value because you can see features moving from left to right"

Sessions as Journey Segments

"Sessions are segments of the journey... we need to connect them into the map."

Sessions are not primary information. They are:

Context for understanding what was worked on
Evidence linking to tasks
Memory for continuity

Display Rule: Show session count as badge/metadata on tasks. Full session details available on drill-down only.

Assumptive Baseline Principle

Principle: Uniform data provides no signal.

Implementation:

Detect repeating values
Hide anything that's consistently the same
Only highlight/show deviations
Mark anomalies prominently

Documentation Package

This design update includes the following comprehensive documents:

Core Design Documents

Software Design Document (SDD)
- System architecture
- Data model & ERD
- API specifications
- Component design
Technical Design Document (TDD)
- Task linking algorithms (Commit→Task, Session→Task)
- Progress calculation logic
- Activity feed prioritization
- Real-time update mechanisms
- Frontend implementation details
Architecture Decision Records (ADRs)
- ADR-001: Task-Centric Architecture
- ADR-002: Checkbox as Source of Truth
- ADR-003: Exception-Based Display
- ADR-004: Session-to-Task Linking
- ADR-005: Real-Time Updates (WebSocket)
- ADR-006: Three-Level Hierarchy
- ADR-007: Activity Feed Prioritization
- ADR-008: Multi-Project Portfolio
UI Component Specifications
- ProjectSummaryBar
- KanbanBoard
- TaskCard
- ActivityFeed
- BlockerPanel
- WorkDistributionChart
- ProjectSelector
- Unified Dashboard Layout
Meeting Transcript
- Full Will-Hal design review (November 27, 2025)
- Key stakeholder quotes
- Design decisions and rationale

Multi-Project Dashboard Design

Complete integrated design package combining:

Software architecture
Technical implementation
UI specifications
Component prompts

Implementation Roadmap

Phase 1: Foundation (Week 1-2)

Priority: P0 - Critical Path

Multi-project data model
- Projects, ProjectPlans, TaskLists, Tasks
- TASK.checked as source of truth
- Status enum: pending/in_progress/review/blocked/done
Task Kanban Board
- 4 columns: Pending | In Progress | Review | Done
- Blocked tasks highlighted within In Progress
- Task cards with checkbox, title, complexity badge
Blocked Task Detection
- Filter status='blocked'
- Days blocked calculation
- Blocker panel UI (orange/amber styling)

Progress Calculation

progress_pct = (COUNT(checked=true) / COUNT(*)) × 100

Phase 2: Linking (Week 3-4)

Priority: P1 - High Value

Commit→Task Linking
- Explicit references (#TASK-123 in commit message)
- Title similarity matching (threshold: 0.7)
- File path overlap analysis
- Confidence scoring
Session→Task Linking
- Keyword extraction (NLP)
- Entity recognition (file paths, identifiers)
- Match score calculation
- Top 5 matches with confidence
Link Management
- Confidence indicators in UI
- User confirm/reject interface
- Link evidence display

Phase 3: Dashboard Assembly (Week 5-6)

Priority: P1 - Core Experience

Project Summary Bar
- All projects with progress bars
- Task counts (N/M completed)
- Commit counts (last 7 days)
- Blocker indicators (red dot)
Activity Feed (5 items max)
- Weighted prioritization algorithm
- Task completed: weight 100
- Task blocked: weight 90
- Commit: weight 50
- Session: weight 30

Work Distribution Chart

weighted_score = commits×3 + sessions×1 + tasks×5
percentage = project_score / total_score × 100

Phase 4: Real-Time Updates (Week 7)

Priority: P2 - Enhanced Experience

WebSocket Infrastructure
- Connection management
- Project subscription model
- Event broadcasting
Event Types
- task.updated, task.completed, task.blocked
- progress.changed
- commit.new, session.ended
Optimistic Updates
- Immediate UI response
- Rollback on failure
- Conflict resolution

Phase 5: Polish & Optimization (Week 8)

Priority: P3 - Production Ready

Caching Strategy
- Portfolio summary: 60s TTL
- Kanban board: 30s TTL
- Activity feed: 60s TTL
- Work distribution: 300s TTL
Performance
- Query optimization
- Materialized views
- Batch loading
Responsive Design
- Mobile: Single column, horizontal Kanban scroll
- Tablet: 2-column layout
- Desktop: Full layout, non-scrolling
Accessibility
- ARIA labels
- Keyboard navigation
- Focus management
- Screen reader support

Data Model

Core Entities

CREATE TABLE projects (
    id UUID PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    status VARCHAR(50) DEFAULT 'active'
);

CREATE TABLE task_lists (
    id UUID PRIMARY KEY,
    plan_id UUID REFERENCES project_plans(id),
    name VARCHAR(255) NOT NULL,
    category VARCHAR(100)
);

CREATE TABLE tasks (
    id UUID PRIMARY KEY,
    list_id UUID REFERENCES task_lists(id),
    title VARCHAR(500) NOT NULL,
    checked BOOLEAN DEFAULT FALSE,  -- SOURCE OF TRUTH
    status VARCHAR(50) DEFAULT 'pending',
    complexity VARCHAR(10),
    blocked_reason TEXT
);

CREATE TABLE llm_sessions (
    id UUID PRIMARY KEY,
    project_id UUID REFERENCES projects(id),
    started_at TIMESTAMP,
    ended_at TIMESTAMP,
    message_count INTEGER,
    summary TEXT
);

CREATE TABLE git_commits (
    sha VARCHAR(40) PRIMARY KEY,
    repo_id UUID REFERENCES git_repos(id),
    message TEXT NOT NULL,
    author VARCHAR(255),
    timestamp TIMESTAMP,
    additions INTEGER,
    deletions INTEGER
);

CREATE TABLE task_commit_links (
    task_id UUID REFERENCES tasks(id),
    commit_sha VARCHAR(40) REFERENCES git_commits(sha),
    confidence DECIMAL(3,2),
    link_type VARCHAR(20),  -- 'explicit' | 'inferred'
    evidence TEXT
);

CREATE TABLE task_session_links (
    task_id UUID REFERENCES tasks(id),
    session_id UUID REFERENCES llm_sessions(id),
    confidence DECIMAL(3,2),
    link_type VARCHAR(20),
    evidence TEXT
);

API Design

REST Endpoints

GET  /api/v1/dashboard
     → DashboardResponse (portfolio + kanban + activity + blockers)

GET  /api/v1/dashboard/portfolio
     → ProjectSummary[] (all projects with progress)

GET  /api/v1/dashboard/activity?limit=5
     → ActivityHighlight[] (top 5 prioritized events)

GET  /api/v1/projects/{id}/kanban
     → KanbanBoard (tasks by status columns)

PATCH /api/v1/tasks/{id}
      → Task (update checked/status)

WebSocket Events

// Server → Client
{
  "type": "task.completed",
  "project_id": "proj-1",
  "task_id": "t-123",
  "changes": { "checked": true, "status": "done" }
}

{
  "type": "progress.changed",
  "project_id": "proj-1",
  "progress_pct": 67.5,
  "tasks_completed": 27,
  "tasks_total": 40
}

// Client → Server
{
  "type": "subscribe",
  "project_ids": ["proj-1", "proj-2", "proj-3"]
}

UI Layout Specification

┌─────────────────────────────────────────────────────────────────────┐
│  CODITECT                      [All Projects ▼]    [⚙ Settings]     │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌─ PROJECT SUMMARY BAR ──────────────────────────────────────┐   │
│  │  Auth System     ████████████░░░░░░ 58%  7/12  3 commits   │   │
│  │  Payment Gateway ████████░░░░░░░░░░ 40%  4/10  1 commit    │   │
│  │  User Dashboard  ██████████████░░░░ 70% 14/20  5 commits   │   │
│  └────────────────────────────────────────────────────────────┘   │
│                                                                     │
│  ┌─ TASK JOURNEY ───────────────────────────────────────────────┐ │
│  │  PENDING   IN PROGRESS    REVIEW        DONE                │ │
│  │  ┌──────┐  ┌──────────┐  ┌────────┐  ┌───────────┐         │ │
│  │  │☐Rate │  │☐Refresh  │  │        │  │☑JWT      │         │ │
│  │  │ Limit│  │ Token    │  │ Empty  │  │☑Auth     │         │ │
│  │  └──────┘  │ 60%████  │  │        │  │☑Login    │         │ │
│  │            │⚠Blocked  │  └────────┘  └───────────┘         │ │
│  │            └──────────┘                                     │ │
│  └──────────────────────────────────────────────────────────────┘ │
│                                                                     │
│  ┌─ RECENT ACTIVITY ─────┐  ┌─ ATTENTION REQUIRED ──────────┐    │
│  │  ✓ JWT complete   2h  │  │  ⚠️ MFA Setup                 │    │
│  │    3 commits, 2 sess  │  │     Blocked: API spec         │    │
│  │  ⎇ abc123: +45/-12 3h │  │     Blocked for: 3 days       │    │
│  │  ✓ Login merged   5h  │  │     [View] [Resolve]          │    │
│  │  💬 Rate limit    6h  │  │                               │    │
│  │  ⚠️ MFA blocked   8h  │  │  No other blockers            │    │
│  └───────────────────────┘  └───────────────────────────────┘    │
│                                                                     │
│  ┌─ WORK DISTRIBUTION (This Week) ──────────────────────────────┐ │
│  │  Auth System     ████████████████████████░░░░░░░░ 45%        │ │
│  │  Payment Gateway █████████████░░░░░░░░░░░░░░░░░░ 25%        │ │
│  │  User Dashboard  ████████░░░░░░░░░░░░░░░░░░░░░░░ 20%        │ │
│  │  Documentation   ████░░░░░░░░░░░░░░░░░░░░░░░░░░░ 10%        │ │
│  └───────────────────────────────────────────────────────────────┘ │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Key Success Metrics

The 5-Second Test Results

✅ Question 1: Which project needs attention? → Answer: Auth System (58%, has blocker) → Source: Project Summary Bar, red dot indicator

✅ Question 2: What tasks are in progress? → Answer: Refresh Token Logic (60% complete), MFA Setup (blocked) → Source: Kanban Board, In Progress column

✅ Question 3: What is blocking progress? → Answer: MFA Setup, blocked for 3 days, awaiting API spec → Source: Blocker Panel (orange highlighted)

✅ Question 4: What completed recently? → Answer: JWT tokens (2h ago), Login form merged (5h ago) → Source: Activity Feed, top 2 items

✅ Question 5: Am I on track? → Answer: Auth System 58% (7/12 tasks), trending positive → Source: Project Summary Bar, progress visualization

Result: All questions answerable in < 5 seconds without scrolling.

Migration from 1.0 to 2.0

Data Transformation Required

Session Data
- Extract session summaries for activity feed
- Link sessions to tasks via NLP
- Hide message-level details from primary view
Task Data
- Ensure all tasks have checked boolean
- Migrate status to new enum
- Identify blocked tasks and reasons
Commit Data
- Parse commit messages for task references
- Calculate file overlap with tasks
- Generate link confidence scores

UI Migration

Remove from Primary View
- Message count displays
- Session duration metrics
- Token usage charts
- Verbose AI summaries
Add to Primary View
- Project summary bar
- Kanban board (if not present)
- Blocker panel
- Work distribution chart
Reorganize
- Session details → Level 3 (deep inspection)
- Commit timeline → Level 2 (drill-down)
- Task history → Level 2 (drill-down)

Appendix: Key Stakeholder Quotes

"The gold isn't in how is it doing it... the real stuff is features, deliverables, targets reached."

"What you want is: How do I get from A to B? What are my obstacles? And what's my route?"

"If it's 40, 40, 40, 40, 40 every time, don't show it."

"5 things that happened and a simple definition of these things."

"Sessions are segments of the journey... we need to connect them into the map."

"The thing you don't want to see [is] the neurons firing. We want to see what we're thinking about."

"A Kanban board has value because you can see features moving from left to right."

"Actual information on a non-scrolling screen."

"You see the map and your route and any obstacles in the way. Even gas and charge are secondary."

"As cars have gotten better, you focus less on the car. You're no longer looking at gauges... you're just looking at the map."

Document History

Version	Date	Author	Changes
2.0	2025-11-27	Design Team	Complete design package based on Will-Hal meeting analysis
1.0	2025-11-26	Design Team	Initial dashboard specification

References:

sdd-activity-dashboard.md
tdd-activity-dashboard.md
ad-rs-activity-dashboard.md
ui-prompts-activity-dashboard.md
multi-project-dashboard-design.md
Meeting Transcript: cuu-ewbn-jrj-2025-11-27T1040-WILL-HAL.txt

This document represents the authoritative 2.0 design update for the Coditect Activity Dashboard, incorporating stakeholder feedback from the November 27, 2025 design review meeting.

Activity Dashboard 2.0 - Design Update

Table of Contents

Executive Summary

Core Transformation

Critical Quote from Stakeholder

Key Design Insights

1. The Navigation Metaphor

2. Exception-Based Display

3. Task-Centric Architecture

4. Three-Level Information Hierarchy

5. The 5-Second Test

Design Philosophy

GPS Not Engine: What to Remove vs Keep

Remove from Primary View

Keep in Primary View

Sessions as Journey Segments

Assumptive Baseline Principle

Documentation Package

Core Design Documents

Multi-Project Dashboard Design

Implementation Roadmap

Phase 1: Foundation (Week 1-2)

Phase 2: Linking (Week 3-4)

Phase 3: Dashboard Assembly (Week 5-6)

Phase 4: Real-Time Updates (Week 7)

Phase 5: Polish & Optimization (Week 8)

Data Model

Core Entities

API Design

REST Endpoints

WebSocket Events

UI Layout Specification

Key Success Metrics

The 5-Second Test Results

Migration from 1.0 to 2.0

Data Transformation Required

UI Migration

Appendix: Key Stakeholder Quotes

Document History

Table of Contents​

Executive Summary​

Core Transformation​

Critical Quote from Stakeholder​

Key Design Insights​

1. The Navigation Metaphor​

2. Exception-Based Display​

3. Task-Centric Architecture​

4. Three-Level Information Hierarchy​

5. The 5-Second Test​

Design Philosophy​

GPS Not Engine: What to Remove vs Keep​

Remove from Primary View​

Keep in Primary View​

Sessions as Journey Segments​

Assumptive Baseline Principle​

Documentation Package​

Core Design Documents​

Multi-Project Dashboard Design​

Implementation Roadmap​

Phase 1: Foundation (Week 1-2)​

Phase 2: Linking (Week 3-4)​

Phase 3: Dashboard Assembly (Week 5-6)​

Phase 4: Real-Time Updates (Week 7)​

Phase 5: Polish & Optimization (Week 8)​

Data Model​

Core Entities​

API Design​

REST Endpoints​

WebSocket Events​

UI Layout Specification​

Key Success Metrics​

The 5-Second Test Results​

Migration from 1.0 to 2.0​

Data Transformation Required​

UI Migration​

Appendix: Key Stakeholder Quotes​

Document History​

Table of Contents

Executive Summary

Core Transformation

Critical Quote from Stakeholder

Key Design Insights

1. The Navigation Metaphor

2. Exception-Based Display

3. Task-Centric Architecture

4. Three-Level Information Hierarchy

5. The 5-Second Test

Design Philosophy

GPS Not Engine: What to Remove vs Keep

Remove from Primary View

Keep in Primary View

Sessions as Journey Segments

Assumptive Baseline Principle

Documentation Package

Core Design Documents

Multi-Project Dashboard Design

Implementation Roadmap

Phase 1: Foundation (Week 1-2)

Phase 2: Linking (Week 3-4)

Phase 3: Dashboard Assembly (Week 5-6)

Phase 4: Real-Time Updates (Week 7)

Phase 5: Polish & Optimization (Week 8)

Data Model

Core Entities

API Design

REST Endpoints

WebSocket Events

UI Layout Specification

Key Success Metrics

The 5-Second Test Results

Migration from 1.0 to 2.0

Data Transformation Required

UI Migration

Appendix: Key Stakeholder Quotes

Document History