Migration
Metric definitions are the operating contract behind your numbers. If the team has not agreed what a metric means, where it comes from, and how it should be calculated, a dashboard will not fix the problem. It will only display the disagreement faster.
Why founders need metric definitions before better dashboards
Most early companies do not start with a metric problem. They start with a language problem. Sales says revenue means closed deals. Finance says revenue means invoiced amounts. Product says active users means anyone who opened the app. Customer success says active users means accounts with meaningful usage. Every definition can be reasonable in context, but they cannot all be the same metric.
This matters more during migration. When you move from spreadsheets to a BI tool, from one warehouse to another, or from manual reporting to automated pipelines, vague definitions become technical debt. The new system forces choices that the company may have avoided for months.
A useful metric definition does not need to be academic. It needs to be clear enough that a person can calculate it, review it, explain it, and know when not to use it.
What a useful metric definition includes
A metric definition should answer four practical questions: what are we measuring, who is included, how is it calculated, and where should people get the number?
For a founder or operator, the goal is not to document every possible edge case on day one. The goal is to make the most important assumptions visible before they create reporting conflict.
- Business question: What decision does this metric help us make?
- Plain-English definition: How would you explain the metric to a new team member?
- Calculation logic: What fields, events, statuses, or amounts are included?
- Grain: What is one unit being counted or aggregated?
- Population: Which customers, users, accounts, transactions, or records are eligible?
- Time logic: Which date controls the metric, such as created date, paid date, event date, renewal date, or close date?
- Exclusions: What should be removed, such as test accounts, internal users, refunds, deleted records, or sandbox activity?
- Source of truth: Which table, model, report, or system should be used?
- Owner: Who can approve changes to the definition?
- Usage notes: When is this metric appropriate, and when is it misleading?
| Definition component | Question it answers | Example |
|---|---|---|
| Business question | Why does this metric exist? | Are retained customers expanding over time? |
| Grain | What is one unit of analysis? | One row per account per month |
| Population | Who or what is eligible? | Paying accounts, excluding test and internal accounts |
| Time logic | Which date controls the period? | Invoice paid date, not invoice created date |
| Source of truth | Where should the number come from? | Curated revenue model in the warehouse |
| Owner | Who approves changes? | Finance owner for meaning, data owner for implementation |
The founder framework for defining a metric
Use a simple sequence: decision, object, event, time, exception, owner. This keeps the discussion grounded in how the business operates instead of how a dashboard happens to be built.
- Decision: Name the decision the metric supports. A metric without a decision often becomes decorative reporting.
- Object: Identify the business object being measured. Is this about users, accounts, subscriptions, invoices, opportunities, orders, tickets, or sessions?
- Event: Identify the action or state that causes the metric to change. Examples include signup, activation, payment, cancellation, renewal, shipment, or ticket resolution.
- Time: Choose the date that determines the reporting period. This is one of the most common causes of mismatched numbers.
- Exception: Decide which records are excluded and why. If the team argues about edge cases every week, the definition is incomplete.
- Owner: Assign one business owner and one technical owner. The business owner decides meaning. The technical owner implements and protects the logic.
This framework is intentionally plain. The harder part is not naming these fields. The harder part is getting the company to make explicit choices.
Do not automate a metric until the business can explain it in one paragraph. Automation makes unclear definitions spread faster.
Example: defining active customers
Active customers sounds simple until people use it for retention, support prioritization, investor reporting, and product engagement. Each use case may require a different definition.
A weak definition would be: active customers are customers who used the product recently.
A stronger definition would be: active customers are paying accounts with at least one non-internal user who completed a qualifying product event in the last 30 days, excluding test accounts, churned accounts, and accounts on free trials.
That stronger version gives the data team something to build and the business something to challenge. It makes the grain clear enough to ask important questions. Are we counting accounts or users? Does login count as usage? What about integrations that create background events? Should trial accounts be included? Which date determines the 30-day window?
The point is not that this is the only correct definition. The point is that it is specific enough to be governed.
Why metric definitions become critical during migration
Migration exposes hidden assumptions. A company may think it is moving dashboards from one tool to another, but it is often moving years of undocumented business logic.
Common migration failures include rebuilding old dashboards without understanding the definitions, comparing old and new numbers without accounting for timing differences, and treating the legacy report as truth even when it contains manual adjustments no one can explain.
Before a migration, classify metrics into three groups. First, board-level and operating metrics that must be defined and reconciled. Second, team metrics that need owner approval before rebuild. Third, low-use metrics that should be archived instead of migrated.
This prevents the migration from becoming a museum project. Not every historical chart deserves to survive.
Before rebuilding a legacy dashboard, decide whether each metric should be preserved, corrected, renamed, or retired.
Common failure modes in metric definitions
Metric definitions fail when they are either too vague to implement or too technical for the business to understand. The definition must sit between business language and technical logic.
- Same name, different meaning: Two teams use the same metric name for different calculations.
- Different names, same meaning: Multiple dashboards show equivalent metrics with different labels, creating unnecessary confusion.
- Hidden filters: A dashboard excludes records in ways that are not visible to the reader.
- Unclear time basis: One report uses created date while another uses paid date, close date, or event date.
- Manual overrides: Spreadsheet adjustments change the number without being captured in the data model.
- Tool-defined logic: A SaaS platform’s built-in metric is treated as the business definition without checking whether it matches company usage.
- No owner: The metric changes when a dashboard changes because no one owns the definition.
| Symptom | Likely cause | What to check first |
|---|---|---|
| Sales and finance report different revenue | Different event dates or recognition logic | Close date, invoice date, payment date, revenue recognition basis |
| Product and success disagree on active customers | Different activity thresholds | Qualifying event list, account versus user grain, trial inclusion |
| Old and new dashboards do not match after migration | Legacy filters or manual adjustments | Hidden filters, spreadsheet edits, archived reports, refresh timing |
| Metric changes after a dashboard edit | Logic lives in the visualization layer | Move logic into a governed model or documented calculation |
| No one knows whether a number is correct | No metric owner | Assign business and technical ownership before further automation |
Which metrics to define first
You do not need a complete metric dictionary before doing useful work. Start with the metrics that create the most risk when misunderstood.
Prioritize metrics that appear in investor updates, board decks, revenue planning, compensation plans, retention analysis, customer health scoring, and executive dashboards. These numbers create decisions, incentives, and expectations. They deserve stronger definitions than exploratory product metrics.
A practical first set often includes revenue, new revenue, expansion, contraction, churn, active customers, activated users, pipeline, conversion rate, gross margin, support volume, and retention. The exact list depends on the business model.
The operator rule is simple: if a number can change priorities, compensation, investor confidence, or customer treatment, define it before automating it.
A lightweight review process that works
Metric governance does not need to start as a committee. In early and growing companies, a lightweight review process is usually better.
- Draft: The metric requester writes the business question, plain-English definition, and expected use.
- Challenge: The business owner and data owner discuss grain, time logic, exclusions, and known edge cases.
- Implement: The technical owner builds the metric in the agreed source of truth.
- Reconcile: The team compares the new number to existing reports and explains material differences.
- Publish: The definition is added to a shared metric catalog, data model documentation, or dashboard notes.
- Change control: Future changes require an owner, a reason, and a note about whether historical reporting should be restated.
This process is enough to prevent most avoidable disputes without slowing the company down.
Diagnostic questions for any disputed metric
When two reports disagree, do not start by blaming the BI tool. Start with the definition.
- Are both reports measuring the same business object?
- Are they using the same grain?
- Are they using the same source system or modeled table?
- Are they filtered to the same population?
- Are they using the same date field and time zone?
- Are test, internal, deleted, refunded, or churned records treated the same way?
- Is one report using cached, delayed, or manually adjusted data?
- Does either report rely on a vendor-defined metric that differs from the company definition?
- Which number is intended for decision-making, and which is informational?
These questions usually reveal that the disagreement is not random. It is a mismatch in assumptions.
Most dashboard disputes are not calculation errors. They are definition conflicts that were never written down.
What good metric definitions look like in practice
A good metric definition is boring in the best way. It has a clear name, a plain-English description, an owner, and implementation logic that does not depend on one person’s memory.
Good definitions also include context. For example, a metric called monthly recurring revenue should clarify whether it includes discounts, trials, usage-based charges, paused subscriptions, credits, tax, refunds, and foreign exchange handling. A metric called conversion rate should clarify the starting population, the success event, the observation window, and whether users can be counted more than once.
The best test is whether a new analyst, operations lead, or founder could read the definition and explain why the number moved. If the definition only makes sense to the person who built the dashboard, it is not finished.
Key takeaways
- Metric definitions are business agreements, not just technical formulas.
- A useful definition clarifies the business question, grain, population, time logic, exclusions, source of truth, and owner.
- Migration is often when undocumented metric logic becomes visible, so define critical metrics before rebuilding dashboards.
- Start with metrics that affect revenue, investor reporting, compensation, retention, and executive decisions.
- Dashboard trust improves when definitions are written, owned, reconciled, and changed deliberately.
Next step
Pick one disputed or high-stakes metric and write its definition using the decision, object, event, time, exception, and owner framework. Then compare it against the dashboard currently used for that metric and document any differences before making technical changes.
- Read Metric Definitions: Plain-English Guide: How to define business metrics so dashboards, migrations, and data models do not quietly disagree.
- Read Metric Definitions: Migration Playbook: A practical playbook for moving from dashboard-specific formulas to trusted, reusable metric definitions.