Metric Definition Sheet

A metric definition that lists what to include is not a definition. Nearly every argument you will ever have about a number is about what got left out, and exclusions are the part almost nobody writes down.

This sheet carries the ordinary fields — name, owner, grain, source, formula. It also carries four that generic templates skip: the exclusion register, the timestamp choice, the late-arrival policy, and the restatement rule.

Why this exists

Write “all completed orders” and you have written a sentence everyone agrees with and nobody computes the same way. Do internal test accounts count? The enterprise customer billed off-platform on a contract? An order canceled and re-placed the same afternoon — one or two? A refund issued in March against a January order: does January change?

Each of those is a real decision somebody already made, in a query, alone, on a deadline. The sheet drags those decisions into writing where the next person can see them. Every exclusion gets a line, a reason, and the name of whoever asked for it. The name matters more than it looks. Exclusions accumulate for years, and an exclusion with no requester attached is the one nobody dares remove — it sits there shaping the number, immune to review, because removing it might break something for somebody unknown.

Then the timestamp. Every event has at least three plausible ones: when it happened, when the record was created, and when your warehouse could first see it. On a calm day they differ by minutes; when something upstream backs up, by days. A sheet that says “by date” without naming which of the three, and in which timezone, has described the metric rather than defined it.

And the field that separates a definition sheet from a glossary entry: does this number change after it is published, and for how long? Late rows arrive, refunds post, a system backfills. Most daily metrics quietly restate themselves for several days, and because nobody calls that a restatement, the person who screenshotted Tuesday’s figure on Tuesday is holding a number that no longer exists anywhere. Write the stabilization window down. “Final after four days” is a field, and if you do not know the number, measuring it is a morning’s work.

How to use it

Fill it in with the query open beside you. A definition written without the code in view records intent, and intent is the one thing already agreed on. Read the filter conditions aloud and write down what they actually do, including the parts that surprise you.

Do grain first. One row equals what — an order, an order line, an order-day? Most fights that look like formula fights are grain fights in disguise, and one sentence at the top settles them.

Then test it: hand the finished sheet to somebody who has never built this metric and ask them to write the query from it. Every difference is a defect in the sheet, not in them.

Keep the “known to be wrong” field populated. Shipping a metric with a known defect is normal and often correct. Shipping one with an undocumented defect is how the defect gets discovered by an executive, from a number that was wrong in an interesting direction.

Where it goes wrong

The sheet documents; it does not govern. Nothing in it stops somebody shipping a second version under the same name, so pair it with a named owner who can refuse a change.

Do not write one of these for every number. A sheet costs an hour to write and half an hour a quarter to keep honest. Across two hundred metrics that is a job nobody has, and half-maintained sheets are worse than none — they still get trusted.

These go stale in one predictable place, and it is not the one people guard. Teams watch the document drifting from the query. The actual failure is the query drifting from the source system’s meaning: somebody upstream adds a status value, or starts using an existing one differently, and every layer below keeps running without error. Put a date on the sheet and re-read it whenever you hear that a source system shipped a release.