Engineering, production, governance, cost, communication · insight-1292
Version KPI definitions like code and restate history when they change
- Evidence type
- practitioner heuristic
- Difficulty
- easy
- Roles
- Data analyst, Data scientist
- Industries
- cross-industry, saas, retail
Summary: situation, action, reason, boundary
Situation
Finance changes 'active customer' from 30 to 90 days of activity in a dashboard, and the trend shows a jump in March (hypothetical).
Action
Hold each KPI's formula, grain, filters, owner and effective date in one reviewed place. On change, publish the new series restated over the old history, annotate the date, and keep the old version available for comparison.
Reason
A metric is an agreement between its producers and consumers, and changing it without a recorded version breaks that agreement as an unannounced schema change does.
Boundary
Executive dashboards, model targets and incentive metrics that persist across quarters.
Symptom or risk
Readers take a definition break for a real change, models trained on the old KPI chase a different quantity, and two decks disagree.
Exceptions
One-off analyses need a note, not a registry.
Trade-offs
Restating history changes numbers people already quoted; announce it.
Pitfalls
Editing a calculated field in a BI tool that nobody reviews.