How to document formula, source, window, granularity, exclusions, and owner so teams, dashboards, and agents interpret every KPI consistently and without ambiguity.
Start with the decision the KPI must inform
A metric exists to answer a question and change an action. Before writing the formula, document who uses it, how often and which decision depends on it. Conversion may mean a form, valid lead, appointment or sale; without purpose, every team chooses the version favoring its interpretation. The contract makes the relationship between indicator and decision explicit.
A data contract turns a metric name into an operational definition. It states purpose, formula, source, granularity, window, exclusions, quality, owner, and dependent actions. When dashboards, reports, and agents use the same contract, discrepancies can be investigated and an update cannot silently change the business's truth.
Document the complete definition
The contract includes canonical name, description, formula, numerator, denominator, unit, source, event, granularity, time zone, window, attribution, filters, exclusions and owner. It also contains inclusion and exclusion examples. The definition must be understandable to business and precise for implementation. If it uses derived fields, it links their contracts so the chain can be reconstructed.
Declare quality, latency and failure behavior
The same metric may update in real time or close days later. The contract specifies frequency, expected delay, completeness thresholds, allowed duplicates, and what happens if a source is missing. A dashboard should show incomplete data instead of filling silence with zero. Alerts are assigned to an owner able to investigate and communicate the impact.
Version changes and protect comparability
Changing a window, event, or filter can alter the historical series. Every change records its date, reason, approver, impact, and strategy: recalculate, maintain two versions, or start a new series. Reports and agents must know the effective dates and avoid mixing definitions. Links to the contract allow someone to understand why two platforms show different values without forcing an artificial match.
Connect contracts with reporting and artificial intelligence
Wiwo.MetriQ can use shared definitions to interpret sources and prepare deliverables; human review validates causes and recommendations. An agent reading revenue or CAC needs the definition, period and limits before explaining a variation. Contracts do not eliminate platform discrepancies: they provide context, ownership and procedure. Trust emerges when every number can be traced from decision to source.
