Skip to main content

ADR-011: ADR Timeline Tracking and Context-Aware Analysis

Status​

Accepted

Date​

2025-11-19

Context​

As our ADR analysis server matured, we identified several limitations in how we track and analyze architectural decisions:

  1. No Temporal Awareness: The system couldn't track when decisions were made or how long they've been in various states
  2. Missing Staleness Detection: No way to identify outdated or neglected ADRs that need attention
  3. Context-Agnostic Thresholds: Same staleness thresholds applied to all projects (startup vs. enterprise)
  4. Manual Action Planning: Users had to manually identify which ADRs need updates or implementation
  5. Performance Concerns: Extracting timeline data could be expensive without smart caching

Decision​

We implemented a comprehensive ADR Timeline Tracking system with the following components:

1. Timeline Extraction (src/utils/adr-timeline-extractor.ts)​

Multi-Source Timeline Extraction:

  • Git History (preferred): Extract creation/update dates from git log
  • Content Parsing (fallback): Parse date fields from ADR content
  • Filesystem (last resort): Use file modification times

Smart Conditional Logic:

  • Only extract when necessary (no timestamp in content, file modified, cache miss)
  • In-memory caching to avoid repeated expensive operations
  • Configurable force-extract option for manual overrides

Timeline Data Structure:

interface BasicTimeline {
  created_at: string; // ISO timestamp
  updated_at: string; // ISO timestamp
  age_days: number; // Days since creation
  days_since_update: number; // Days since last modification
  staleness_warnings: string[]; // Generated warnings
  extraction_method: 'git' | 'content' | 'filesystem';
}

2. Project Context Detection (src/utils/adr-context-detector.ts)​

Automatic Project Phase Detection:

  • Startup: High commit rate (>50/week), frequent ADRs (>3/month)
  • Growth: Moderate commits (20-50/week), regular ADRs (>1/month)
  • Mature: Stable commits (5-20/week), occasional ADRs
  • Maintenance: Low commits (<5/week), rare ADRs (<0.5/month)

Adaptive Threshold Profiles:

THRESHOLD_PROFILES = {
  startup: {
    staleProposedDays: 14, // 2 weeks max
    acceptedUnimplementedDays: 21,
    outdatedAdrDays: 60,
    rapidChangeDays: 3,
  },
  growth: {
    staleProposedDays: 30, // 1 sprint cycle
    acceptedUnimplementedDays: 45,
    outdatedAdrDays: 90,
    rapidChangeDays: 7,
  },
  mature: {
    staleProposedDays: 90, // 1 quarter
    acceptedUnimplementedDays: 90,
    outdatedAdrDays: 180,
    rapidChangeDays: 14,
  },
  maintenance: {
    staleProposedDays: 180, // 6 months
    acceptedUnimplementedDays: 180,
    outdatedAdrDays: 365,
    rapidChangeDays: 30,
  },
};

ADR Type Modifiers:

  • Infrastructure ADRs: 1.5x longer timelines (complex deployments)
  • Security ADRs: 0.8x shorter timelines (urgent)
  • Refactoring ADRs: 1.2x longer timelines (low priority)
  • Feature ADRs: 1.0x baseline

3. Action Item Analyzer (src/utils/adr-action-analyzer.ts)​

Automated Action Generation:

  • Analyzes all ADRs with timeline data
  • Generates prioritized action items based on:
    • ADR status (proposed, accepted, deprecated)
    • Age and staleness
    • Implementation status
    • Project context and thresholds

Action Urgency Levels:

  • Critical (P0): Blocking issues, security risks
  • High (P1): Stale proposed ADRs, long-unimplemented decisions
  • Medium (P2): Outdated ADRs needing review
  • Low (P3): Minor updates, documentation improvements

Work Queue Structure:

interface AdrWorkQueue {
  summary: {
    totalActions: number;
    criticalCount: number;
    highCount: number;
    mediumCount: number;
    lowCount: number;
  };
  actions: ActionItem[]; // Sorted by urgency
  recommendations: string[];
}

4. Integration​

Enhanced ADR Discovery:

  • discoverAdrsInDirectory() now accepts includeTimeline option
  • Timeline data automatically attached to each discovered ADR
  • Optional action generation with generateActions flag

New MCP Tool (src/index.ts:6800-6950):

  • analyze_adr_timeline: Comprehensive timeline analysis with action items
  • Parameters:
    • adrDirectory: Directory to analyze
    • generateActions: Enable action item generation
    • thresholdProfile: Manual profile override
    • autoDetectContext: Auto-select profile (default: true)

5. Cache Implementation Decision​

Problem: The existing cache.ts is designed for prompt-driven AI operations (returns prompts for AI to execute), but timeline extraction needs synchronous in-memory caching for performance.

Solution: Implemented a simple in-memory cache directly in adr-timeline-extractor.ts:

  • Map<string, CacheEntry> for O(1) lookup
  • TTL-based expiration
  • Automatic cleanup on retrieval
  • No external dependencies

Why Not Use cache.ts:

  • cache.ts returns { prompt, instructions, context } for AI delegation
  • Timeline extractor needs immediate, synchronous cache access
  • In-memory cache is simpler and more appropriate for this use case

Consequences​

Positive​

  1. Temporal Awareness: System now understands ADR lifecycles and aging
  2. Automated Action Planning: Generates prioritized todo lists automatically
  3. Context-Aware Analysis: Thresholds adapt to project phase and velocity
  4. Smart Performance: Conditional extraction minimizes expensive operations
  5. Type Safety: ADR type modifiers provide realistic timelines
  6. Better User Experience: Users get actionable insights, not just data

Negative​

  1. Increased Complexity: More code to maintain (4 new utility files)
  2. Git Dependency: Git extraction requires git to be available
  3. Cache Divergence: Two cache systems (prompt-driven and in-memory)
  4. Context Detection Accuracy: Auto-detection may misclassify edge-case projects

Neutral​

  1. Breaking Change: discoverAdrsInDirectory() signature changed from 3 params to 2 params + options object
  2. Memory Usage: In-memory cache adds modest memory overhead
  3. Learning Curve: Users need to understand threshold profiles

Implementation Notes​

Files Created​

  • src/utils/adr-timeline-extractor.ts - Multi-source timeline extraction
  • src/utils/adr-context-detector.ts - Project context detection
  • src/utils/adr-action-analyzer.ts - Action item generation
  • src/utils/adr-timeline-types.ts - Shared type definitions

Files Modified​

  • src/utils/adr-discovery.ts - Added timeline integration
  • src/index.ts - Added analyze_adr_timeline MCP tool
  • 20+ files - Updated discoverAdrsInDirectory() call sites

Testing​

  • Manual verification: Timeline extraction working correctly
  • Git extraction: Successfully extracts from git history
  • Fallback chain: Content → filesystem fallback working
  • Cache: In-memory cache functioning as expected

Future Enhancements​

  1. Persistent Cache: Move timeline cache to disk for cross-session persistence
  2. ML-Based Context Detection: Use machine learning to improve phase detection
  3. Custom Thresholds: Allow users to define custom threshold profiles
  4. Timeline Visualization: Generate charts showing ADR lifecycle trends
  5. Notification Integration: Alert users when ADRs become stale
  6. ADR Dependencies: Track dependencies between ADRs in timeline
  • ADR-003: Memory-Centric Architecture (cache system design)
  • ADR-001: MCP Protocol Implementation (tool integration)

References​

  • Git log extraction: git log --follow --format="%ai" --diff-filter=A -- <file>
  • Context detection metrics: Commit frequency, ADR creation rate, team velocity
  • Urgency scoring: Based on ADR status, age, and project context