ADR-051: Work Discovery System

Status

Accepted - January 3, 2026

Context

CODITECT users need a systematic way to:

1. Determine what work to do next across sessions
2. Track work progress and log activities
3. Identify blockers and hot spots
4. Generate handoff documentation
5. Preserve context between sessions

Previously, users relied on manual review of project plans, git history, and memory to decide next steps. This was error-prone and context was frequently lost between sessions.

Decision

Implement a Work Discovery System consisting of 7 interconnected components:

Core Components

Component	Type	Purpose
/work-next	Command	Multi-source analysis to recommend next work
/work-log	Command	Log completed work to context database
/blockers	Command	Surface blocked tasks with resolution paths
/momentum	Command	Show activity hot spots and velocity
/handoff	Command	Generate comprehensive handoff documentation
work-discovery-analyst	Agent	Analyze and synthesize project state
session-summarizer	Agent	Summarize sessions for handoffs

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                      WORK DISCOVERY SYSTEM                           │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐          │
│  │  /work-next  │    │  /work-log   │    │  /blockers   │          │
│  │              │    │              │    │              │          │
│  │  • Discovery │    │  • Capture   │    │  • Surface   │          │
│  │  • Analysis  │    │  • Log       │    │  • Analyze   │          │
│  │  • Recommend │    │  • Store     │    │  • Resolve   │          │
│  └──────┬───────┘    └──────┬───────┘    └──────┬───────┘          │
│         │                   │                   │                   │
│         └───────────────────┼───────────────────┘                   │
│                             │                                       │
│                             ▼                                       │
│                    ┌────────────────┐                               │
│                    │ sessions.db    │ (Tier 3)                      │
│                    │                │                               │
│                    │  • Work logs   │                               │
│                    │  • Decisions   │                               │
│                    │  • Blockers    │                               │
│                    │  • Sessions    │                               │
│                    └────────┬───────┘                               │
│                             │                                       │
│         ┌───────────────────┼───────────────────┐                   │
│         │                   │                   │                   │
│  ┌──────┴───────┐    ┌──────┴───────┐    ┌──────┴───────┐          │
│  │  /momentum   │    │  /handoff    │    │   Agents     │          │
│  │              │    │              │    │              │          │
│  │  • Velocity  │    │  • Summary   │    │  • Analyst   │          │
│  │  • Hot spots │    │  • Handoff   │    │  • Summarize │          │
│  │  • Trends    │    │  • Preserve  │    │  • Recommend │          │
│  └──────────────┘    └──────────────┘    └──────────────┘          │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

Data Flow

Session Start                       During Session                    Session End
     │                                    │                               │
     ▼                                    ▼                               ▼
┌─────────┐                        ┌─────────────┐                 ┌───────────┐
│/work-   │                        │ /work-log   │                 │ /handoff  │
│ next    │                        │             │                 │           │
└────┬────┘                        └──────┬──────┘                 └─────┬─────┘
     │                                    │                               │
     ▼                                    ▼                               ▼
Recommend      ──────────────────▶    sessions.db   ◀────────────    Summarize
Next Work                              (Stores)                      Session
     │                                    │                               │
     ▼                                    ▼                               ▼
/blockers  ◀─────────────────────▶   /momentum   ◀────────────────▶   Agents
(Blockers)                          (Hot Spots)                     (Analysis)

Components Detail

1. /work-next Command

Purpose: Comprehensive work discovery with multi-source analysis.

8-Step Discovery Process:

1. Query sessions.db for recent work (/cxq --recent 200)
2. Find and analyze active project plan (PILOT*.md)
3. Check tasklist status (TASKLIST*.md)
4. Analyze git history (git log --oneline -20)
5. Check uncommitted changes (git status --short)
6. Analyze directory changes
7. Review recent sessions (~/.claude/projects/*.jsonl)
8. Check checkpoint status

Output: Interactive recommendations with priority levels.

2. /work-log Command

Purpose: Quick activity logging for context preservation.

Entry Format:

{
  "type": "work_log",
  "timestamp": "2026-01-03T12:30:00Z",
  "description": "Fixed cart API response mismatch",
  "category": "bugfix",
  "files": ["cart.service.ts", "useCart.ts"],
  "task_ref": "A.3",
  "session_id": "current-session-uuid"
}

Categories: feature, bugfix, refactor, docs, test, deploy, config, research

3. /blockers Command

Purpose: Surface all blocked tasks with resolution paths.

Detection Patterns:

• ⏸️ - Paused/blocked emoji
• BLOCKED - Explicit status
• waiting on, depends on, blocked by - Dependencies
• needs - Missing requirement

Priority Levels: Critical, High, Normal, Low

4. /momentum Command

Purpose: Show activity hot spots and velocity.

Indicators:

• 🔥🔥🔥 Very Hot (10+ changes)
• 🔥🔥 Hot (5-9 changes)
• 🔥 Warm (2-4 changes)
• ➖ Cool (1 change)
• ❄️ Cold (no changes)

Grouping: By directory, by track, by author

5. /handoff Command

Purpose: Generate comprehensive handoff documentation.

Includes:

• Executive summary
• Accomplishments
• Work in progress
• Blockers
• Key decisions
• Momentum
• Files to review
• Environment state
• Next steps
• Cold start context

6. work-discovery-analyst Agent

Purpose: Analyze project state from multiple sources.

Capabilities:

• Multi-source data gathering
• Priority assessment (Urgency, Momentum, Impact, Readiness)
• Recommendation generation
• Context synthesis

7. session-summarizer Agent

Purpose: Summarize sessions for handoffs and context preservation.

Extracts:

• Key accomplishments
• Decisions made with rationale
• Work-in-progress state
• Blockers encountered
• Files modified
• Patterns and anti-patterns

Storage Integration (ADR-118 Compliant)

Work logs are stored in sessions.db (Tier 3):

-- In sessions.db
CREATE TABLE IF NOT EXISTS work_logs (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    session_id TEXT NOT NULL,
    timestamp TEXT NOT NULL,
    description TEXT NOT NULL,
    category TEXT,
    files TEXT,  -- JSON array
    task_ref TEXT,
    created_at TEXT DEFAULT (datetime('now'))
);

CREATE INDEX idx_work_logs_session ON work_logs(session_id);
CREATE INDEX idx_work_logs_timestamp ON work_logs(timestamp);
CREATE INDEX idx_work_logs_task ON work_logs(task_ref);

Usage Examples

Session Start Workflow

# 1. Run work discovery
/work-next

# 2. Review recommendations and select
> 1  # Select recommended action

# 3. Or ask for specific guidance
/agent work-discovery-analyst "What's blocking Track C?"

During Session

# Log completed work
/work-log "Implemented cart API endpoint" --category feature --task "A.3"

# Log with files
/work-log "Fixed auth bug" --category bugfix --files "auth.ts,login.tsx"

# Quick log
/done "Completed checkout refactor"  # alias for /work-log

Check Status

# See blockers
/blockers
/blockers --track A  # Filter by track
/blockers --critical  # Critical only

# See momentum
/momentum
/momentum --hours 24  # Last 24 hours
/momentum --by-track  # Group by project track

Session End

# Generate handoff
/handoff

# Save to file
/handoff --save handoff-2026-01-03.md

# Quick end-of-day
/handoff --eod

Quick Reference

Task	Command
What should I do next?	/work-next
Log completed work	/work-log "description"
See blockers	/blockers
See activity	/momentum
Create handoff	/handoff
Full analysis	/agent work-discovery-analyst "question"
Summarize session	/agent session-summarizer "summarize"

Command Aliases

Alias	Full Command
/next	/work-next
/wn	/work-next
/log	/work-log
/wl	/work-log
/done	/work-log
/blocked	/blockers
/impediments	/blockers
/activity	/momentum
/hotspots	/momentum
/transition	/handoff
/eod	/handoff

Consequences

Positive

1. Context Preservation - Work state persists across sessions
2. Efficient Orientation - Quick start for new sessions
3. Blocker Visibility - Blocked work surfaces automatically
4. Activity Tracking - Momentum and velocity visible
5. Handoff Quality - Comprehensive handoff documentation

Negative

1. Learning Curve - Multiple commands to learn
2. Discipline Required - Users must log work for best results
3. Storage Overhead - sessions.db grows over time

Neutral

1. Integration Required - Components work best together
2. Customization - Different workflows may need adaptation

Related Documents

• ADR-049: Component Creation Lifecycle
• ADR-050: Submodule Initialization Lifecycle
• ADR-118: Four-Tier Database Architecture
• MEMORY-MANAGEMENT-GUIDE.md

---

Author: CODITECT Team Approved: January 3, 2026 Migration: Migrated from cloud-infra per ADR-150 on 2026-02-03