A dashboard shows 412 producing wells. The report from accounting says 398. Both are correct. Each counts something different, and nobody wrote down what.
Most arguments about numbers are arguments about definitions. You settle them once, in writing, or you have them again every month.
Where the disagreement hides
Take “producing well count.” Ask five people and you can get five answers. A well that produced on any day this month. A well that produced on the last day of the month. A well with a status of Producing in the system of record. A well with a nonzero allocated volume. A well that was on production for more than half the days.
Each is a reasonable definition. They differ most when wells are shut in for workovers, when a well flows for a day and then quits, and at month boundaries. The gap between them is the gap between two reports.
Downtime has the same problem. Is a planned shutdown for maintenance downtime? Is a well that is curtailed by a pipeline still “up”? Does a one-hour trip count, or only events longer than some threshold? Different groups use different rules, and most of them use the rule they inherited without checking it.
What a dictionary entry holds
A metric dictionary is a short document, one entry per metric. It does not need special software to start. A shared spreadsheet or a markdown file in version control is enough.
Each entry answers the questions that cause disputes:
- Name and plain-language meaning. One sentence a field supervisor and a finance analyst would both accept.
- Formula. Exact, including filters. “Count of distinct wells where daily allocated oil volume is greater than zero on at least one day in the period.”
- Grain and period. Per well per day, per facility per month, and how the period boundaries work, including any production day start hour.
- Unit and basis. Barrels, thousand cubic feet, and for gas the pressure and temperature base if your source states one.
- Source of record. Which system owns the inputs. When two systems disagree, which one wins.
- Owner. A named person or role who can approve a change.
- Known exclusions. Test wells, injection wells, wells in a particular status, and why.
- Effective date and history. When the definition took effect and what it replaced.
If an entry cannot answer one of these, you have found a definition nobody owns. That is useful to know.
Start with ten
Do not try to document every number in the company. You will stall.
Pick the ten metrics that appear on the reports people argue about. Count how many dashboards or spreadsheets use each one. A metric that shows up in six places with six formulas is the first candidate.
For each, collect every existing formula. Put them side by side and compute all of them for last month. The differences, in plain numbers, are the most persuasive argument you will have for settling on one definition.
If the variants serve different purposes, name them differently. “Wells producing at month end” and “wells with production in month” are both legitimate. They are not the same metric, and they should not share a name.
Make the definition run
A dictionary that lives in a document drifts from the code. The test for whether it works is whether a second person, reading only the entry, would compute the same number.
Try it. Give an entry to someone who did not write it and ask them to produce last month’s value from the raw data. If their answer differs from the dashboard, either the entry is ambiguous or the dashboard is wrong. Both are worth knowing before an executive asks.
Once definitions are stable, put the formula in one place in your transformation layer and have every report read from there. A metric computed in three dashboards is three definitions that will diverge. A metric computed once in a shared model is one definition, and changing it changes every report together.
Change control without bureaucracy
Definitions will change. A new regulation, a new system, a better understanding of the business. That is normal.
What hurts is a silent change. Last quarter’s number was computed one way and this quarter’s another, and the trend line now means nothing.
Keep it light:
- The owner approves the change and records the date.
- The old and new values are computed side by side for at least one prior period, so people can see the step.
- Reports that show the metric note the change, or restate history under the new rule.
If you cannot restate history because the inputs do not exist, say so on the report. A visible discontinuity is better than a hidden one.
Why this comes before the dashboard
Building the dashboard first is tempting, because a chart is visible progress. It also locks in whatever definition the builder guessed, and the guess gets treated as the answer once people start quoting it.
A dictionary entry takes an hour or two. Untangling a definition that has been quoted in board decks for a year takes a lot longer, mostly in conversations.
When you hire a consultant or a contractor to build reporting, ask for the dictionary as a deliverable alongside the dashboards. If it comes back empty, the dashboard is not finished, whatever it looks like.

