Track Trends

Generate historical analysis of repository health metrics over time to identify improvement or degradation patterns.

Prerequisites

Omen CLI must be installed and available in PATH.

When to Use

• Quarterly engineering health reports
• Release retrospectives
• Tracking debt paydown initiatives
• Justifying refactoring investments with data
• Identifying gradual quality degradation

Workflow

Step 1: Run Trend Analysis

Use the Omen CLI to analyze historical scores:

# Last 3 months, weekly sampling (default)
omen score trend --since 3m

# Last 6 months for quarterly report
omen score trend --since 6m --period monthly

# Full year for annual review
omen score trend --since 1y --period monthly

Parameters:

• --since: How far back to analyze (3m, 6m, 1y, 2y, 30d, 4w, all). Defaults to all (full history).
• --period: Sampling frequency (daily, weekly, monthly)

Step 2: Interpret Results

The output includes:

Field	Meaning
Score	Composite health score (0-100)
Slope	Points gained/lost per period
R-squared	How consistent the trend is (0-1)
Correlation	Direction and strength (-1 to 1)

Trend interpretation:

• Positive slope = improving health
• Negative slope = degrading health
• High R-squared (>0.7) = consistent trend
• Low R-squared (<0.3) = volatile/no clear trend

Step 3: Analyze Component Trends

Each component has its own trend statistics:

Component	What It Measures
Complexity	Function complexity violations
Duplication	Code clone ratio
SATD	Self-admitted technical debt
TDG	Technical Debt Gradient
Coupling	Cyclic dependencies, instability
Smells	Architectural issues
Cohesion	Class cohesion (LCOM)

Look for diverging trends - overall score improving but one component degrading.

Output Format

Generate a trend report:

# Repository Health Trend Report
Period: [Start Date] to [End Date]

## Executive Summary

| Metric | Start | End | Change | Trend |
|--------|-------|-----|--------|-------|
| Overall Score | 72 | 85 | +13 | Improving |
| Complexity | 68 | 91 | +23 | Strong improvement |
| Duplication | 75 | 66 | -9 | Degrading |
| SATD | 80 | 85 | +5 | Stable improvement |
| TDG | 82 | 88 | +6 | Improving |
| Coupling | 70 | 75 | +5 | Stable |
| Smells | 100 | 100 | 0 | Excellent |
| Cohesion | 95 | 100 | +5 | Excellent |

## Trend Analysis

**Overall trajectory:** Score improving at +2.1 points/month (R-squared: 0.89)

**Key observations:**
1. Complexity improved significantly after refactoring sprint in [month]
2. Duplication trending down - clone detection shows new patterns emerging
3. Technical debt (SATD) being addressed consistently

## Component Deep Dive

### Complexity (Strong Improvement)
- Started: 68 (15 functions over threshold)
- Current: 91 (3 functions over threshold)
- Key changes: Refactored payment processor, split auth handler

### Duplication (Concerning)
- Started: 75 (4.2% duplication)
- Current: 66 (6.1% duplication)
- Action needed: New handler patterns being copy-pasted

## Recommendations

### Immediate Actions
1. Address duplication in `handlers/` directory
2. Review new code for copy-paste patterns

### Next Quarter Goals
1. Maintain complexity below 5 violations
2. Reduce duplication back to <5%
3. Continue SATD remediation pace

## Historical Data Points

| Date | Commit | Score | Cx | Dup | SATD | TDG | Coup | Smell | Coh |
|------|--------|-------|-----|-----|------|-----|------|-------|-----|
| 2024-01 | abc123 | 72 | 68 | 75 | 80 | 82 | 70 | 100 | 95 |
| 2024-02 | def456 | 76 | 75 | 72 | 82 | 84 | 72 | 100 | 98 |
| 2024-03 | ghi789 | 85 | 91 | 66 | 85 | 88 | 75 | 100 | 100 |

CI/CD Integration

Add trend checks to release pipelines:

# Fail if score dropped more than 5 points in last month
omen -f json score trend --since 1m | \
  jq -e '.total_change >= -5'

# Generate trend report for release notes
omen -f markdown score trend --since 3m > TREND_REPORT.md

Interpreting Patterns

Healthy Repository

• Stable or improving score over time
• No component consistently degrading
• Occasional dips followed by recovery

Technical Debt Accumulation

• Gradual score decline (negative slope)
• Multiple components trending down
• SATD count increasing

Successful Refactoring Initiative

• Score jump at specific point in time
• Sustained improvement after intervention
• TDG and complexity improving together

Feature Rush Pattern

• Score drops during crunch periods
• Duplication spikes (copy-paste coding)
• Recovery during stabilization sprints