Decision History Dashboard

Visualize how OrchestKit evolved with Claude Code versions, understand WHY decisions were made, and track best practices adoption.

Overview

• View architecture decisions chronologically
• Track Claude Code version evolution (2.1.0 → 2.1.16+)
• Understand rationale behind each decision
• Generate Mermaid timeline diagrams for docs
• Query decisions by category, CC version, or date range

Quick Start

# List recent decisions
node hooks/bin/decision-history.mjs list

# Show decisions for specific CC version
node hooks/bin/decision-history.mjs list --cc-version 2.1.16

# Generate Mermaid timeline
node hooks/bin/decision-history.mjs mermaid --output timeline.md

# Filter by category
node hooks/bin/decision-history.mjs list --category security

# Show last 30 days
node hooks/bin/decision-history.mjs list --days 30

# View statistics
node hooks/bin/decision-history.mjs stats

# Search decisions
node hooks/bin/decision-history.mjs search "typescript hooks"

Data Sources

Decisions are aggregated from multiple sources (priority order):

Source	Location	Description
Session	.claude/context/knowledge/decisions/active.json	Recent in-session decisions
CHANGELOG	CHANGELOG.md	Parsed version history
Coordination	.claude/coordination/decision-log.json	Multi-instance decisions

CLI Commands

# List decisions with filters
decision-history list [--cc-version VER] [--category CAT] [--days N] [--limit N]

# Show decision details
decision-history show <decision-id>

# Display timeline view
decision-history timeline [--group-by cc_version|category|month]

# Show statistics
decision-history stats

# Generate Mermaid diagram
decision-history mermaid [--output FILE] [--full] [--group-by FIELD]

# Sync from all sources (refresh cache)
decision-history sync

# Search decisions
decision-history search <query>

Output Formats

ASCII Table (Default)

┌────────────┬──────────┬────────────────────────────────────────────┬────────────┐
│ Date       │ CC Ver   │ Summary                                    │ Category   │
├────────────┼──────────┼────────────────────────────────────────────┼────────────┤
│ 2026-01-21 │ 2.1.16   │ **CC 2.1.16 Support**: Full Claude Code... │ architectu │
│ 2026-01-18 │ 2.1.16   │ **New agent-browser Skill** - Complete V...│ ai         │
│ 2026-01-18 │ 2.1.16   │ **Hook Stdin Consumption** - Fixed 39 ho...│ hooks      │
└────────────┴──────────┴────────────────────────────────────────────┴────────────┘

ASCII Timeline

Decision History Timeline
════════════════════════════════════════════════════════════════

CC 2.1.16
  ├── 2026-01-21 ── CC 2.1.16 Support: Full integration
  │   HIGH │ architecture
  ├── 2026-01-18 ── New agent-browser Skill
  │   MEDIUM │ ai

CC 2.1.11
  ├── 2025-12-20 ── Setup Hooks for Initialization
  │   HIGH │ lifecycle

Mermaid Timeline

timeline
    title OrchestKit Evolution with Claude Code
    section CC 2.1.16
        Task Management System : architecture
        agent-browser Integration : ai
    section CC 2.1.11
        Setup Hooks : lifecycle
        Self-healing : architecture

Decision Schema

Each decision includes:

interface Decision {
  id: string;              // e.g., "4.28.0-architecture-1"
  date: string;            // ISO date: "2026-01-21"
  summary: string;         // Brief description
  rationale?: string;      // Full explanation
  ccVersion?: string;      // e.g., "2.1.16"
  pluginVersion?: string;  // e.g., "4.28.0"
  category: string;        // e.g., "architecture", "security"
  impact: 'high' | 'medium' | 'low';
  status: 'proposed' | 'implemented' | 'deprecated' | 'superseded';
  source: 'changelog' | 'session' | 'coordination' | 'mem0';
  bestPractice?: string;   // Related best practice
  entities?: string[];     // Related concepts
}

Implementation

This skill is implemented in TypeScript as part of the hooks infrastructure:

File	Purpose
hooks/src/lib/decision-history.ts	Core module (parser, aggregator, formatters)
hooks/bin/decision-history.mjs	CLI entry point
hooks/dist/hooks.mjs	Bundled module (via esbuild)

Key Functions

• parseChangelog(content) - Parse CHANGELOG.md into structured data
• aggregateDecisions() - Combine all sources with deduplication
• filterDecisions(decisions, options) - Apply CC version, category, date filters
• formatTable(decisions) - ASCII table output
• formatTimeline(decisions) - ASCII timeline grouped by version
• formatMermaid(decisions) - Mermaid diagram generation
• formatStats(aggregated) - Statistics summary

Key Decisions

Decision	Choice	Rationale
Language	TypeScript ESM	Consistent with hooks migration, type safety
CLI pattern	Node.js script	Same as hooks infrastructure
Timeline format	Mermaid	GitHub-native, docs-friendly
Data aggregation	Multi-source	CHANGELOG + session + coordination
Caching	File-based	.claude/feedback/changelog-decisions.json

References

• CLI Commands - Detailed command reference
• Data Schema - Full schema specification
• CC Version Mapping - Feature to CC version map

Related Skills

• release-management: Version tracking and changelog generation
• context-compression: Context management patterns
• mem0-memory: Memory CRUD operations (optional integration)