Refactor Metric

Definition

Refactor measures the percentage of code changes that modify lines of code that are 21 days old or older at the time of change.

It is calculated from commit activity across all included branches within the selected time range, regardless of PR state.

How Refactor Is Calculated

Refactor is calculated using the following formula: (Lines modified that are ≥21 days old ÷ Total lines changed) × 100

• Code ≥ 21 days old → counted as Refactor
• Code < 21 days old → counted as Rework

Where:

• Lines modified = changes to existing lines of code
• Total lines changed = lines added + lines modified + lines deleted

The headline value represents:

Total lines modified that are ≥21 days old ÷ Total lines changed across all included branches and commits in the selected time range

This is a weighted percentage, calculated across the entire selected time range — not an average of daily values. 

How the Metric Is Displayed in the Dashboard

The metric card displays two types of values:

1. Headline Value (e.g., 8.21%)

The large percentage at the top represents the aggregated Refactor percentage across the selected time range.

It reflects the proportion of modified lines relative to total code changes across all included branches during that period.

2. Time-Based Values in the Chart

The line chart shows Refactor aggregated per time bucket (for example, daily).

Each point represents: Modified lines ≥ 21 days old ÷ Total lines changed within that time bucket

Clicking a point displays:

• The Refactor percentage for that date
• The total number of code changes analyzed

Daily values are calculated independently per bucket and do not average to produce the headline value.

Why This Metric Is Useful

Refactor provides visibility into:

• How much development effort is spent improving existing code
• Whether technical debt is being actively addressed
• The balance between feature delivery and codebase maintenance

Sustained refactoring can improve:

• Maintainability
• Readability
• Long-term stability

However, excessive refactoring during high-delivery periods may indicate:

• Unplanned clean-up work
• Hidden stability issues
• Misaligned sprint priorities

How to Interpret Refactor

Refactor should be interpreted in context.

Consider:

• The stage of the product lifecycle
• Release pressure
• Ongoing architectural changes
• Team maturity

As general guidance:

• 20–40% of changes spent on refactoring is often considered healthy.
• Extremely low Refactor may signal accumulating technical debt.
• Extremely high Refactor may delay feature delivery.

Refactor should be evaluated alongside:

• New Work
• Rework
• Cycle Time

Data Sources

Refactor is derived from:

• Refactor is derived from commit-level repository diff data
• The metric includes all qualifying commits on included branches within the selected time range
• PR status (open, merged, draft, or without an associated PR) does not affect inclusion
• Line age is determined using Git history

Tunable Configurations

Refactor behavior may depend on:

• The definition of “legacy code” (e.g., 21-day threshold)
• Repository inclusion and filtering rules
• How modified lines are classified

Limitations

• Refactor measures code modification volume, not impact.
• It does not distinguish between minor edits and architectural improvements.
• It does not evaluate whether refactoring was necessary or strategic.
• Formatting-only changes can inflate results.
• Small datasets may produce volatile percentages.
• Refactor is commit-based and may include activity from branches that are stale or not associated with a merged PR.
• High percentages on a specific date may reflect concentrated legacy code modification on a single branch.

Refactor reflects change distribution, not code quality.

Stakeholder Use Cases

Engineering Managers

• Monitor balance between feature work and technical debt reduction
• Detect over-refactoring during high-delivery periods

Developers

• Justify time spent improving code quality
• Track long-term codebase health

Product Leaders

• Understand delivery trade-offs during roadmap planning