# 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**:
```typescript
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**:
```typescript
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**:
```typescript
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
## Related ADRs
- 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