How is a metric dictionary different from just writing good queries?

A query computes a number; a metric dictionary decides what the number is supposed to mean before anyone writes a query. Without it, two correct queries can return two different 'active users' because they encode two unstated definitions. The dictionary is the agreed definition every query then cites — it's what makes numbers reproducible and comparable across people and months, not just runnable.

Who should own the metric dictionary?

One owner per metric — usually the analyst or analytics lead closest to it — plus one overall owner for the file. The whole value is that it's a single source of truth; if everyone can edit it freely, it drifts back into the inconsistency it was meant to fix. Treat a definition change as a reviewed, logged update with an approver, not a free-for-all, and re-run the playbook only when a metric genuinely changes.

What do I need before I start?

A recent dashboard, board deck, or weekly report so you can list every metric you actually publish, plus the queries or spreadsheets behind a few of them so Claude can read what each number currently computes. Bring any standing disputes too — 'we never agree on churn' is exactly the kind of conflict this playbook is built to resolve on the page.

Does the dictionary guarantee our numbers are correct?

No — it guarantees they're consistent, which is different. The dictionary makes everyone count the same thing the same way; it doesn't certify the underlying data is clean or the logic is bug-free. You still reconcile every result against a known total and audit the source data. Consistent-and-wrong is still wrong; the dictionary just removes the second, avoidable failure of consistent-and-disagreeing.

Build the metric dictionary every query and report inherits

when to reach for this

Every data team has the same quiet failure: two analysts pull 'active users' and get two different numbers, and both are right — because nobody wrote down what 'active' means. At enterprise scale that's not a curiosity, it's a credibility leak: the board deck and the ops dashboard disagree, and the team spends meetings reconciling definitions instead of finding insights. The fix is a metric dictionary — a metrics.md with one canonical entry per metric: the plain-English meaning, the exact logic, who owns it, and the edge cases. Build it once and every other Data playbook gets sharper, because 'our numbers' finally points at one document. This is the what we count; the other playbooks are how we count it.

gather this first

The metrics you actually report — pull a recent dashboard, board deck, or weekly update and list every number on it. Even the contested ones (especially the contested ones).
The queries or spreadsheets behind a few of them, so Claude can read what the number currently computes, not just what people say it means.
Who would answer for each number if a VP challenged it — and any standing disputes ('we never agree on churn') so they get resolved on the page, not in the next meeting.

the workflow

Inventory the metrics you report — and surface the conflicts

Open the folder with your dashboard exports and the queries behind them in Claude Desktop, and ask in the chat — no terminal needed. Before defining anything, get the full list and catch the same metric defined two ways. The duplicates are the whole reason you're here.

you ask

Here's a recent dashboard and the queries behind it. List every distinct metric we report. For each, tell me what it appears to measure from the query, and flag any case where the same name is computed two different ways, or two names clearly mean the same thing. Don't write definitions yet — just give me the inventory and the conflicts.

what you get back A clean inventory plus a conflict list: "'active users' is COUNT(DISTINCT user_id) in the exec query but counts sessions in the ops one; 'revenue' includes refunds in one place, excludes them in another." The conflicts are the metrics to resolve first.

Resist defining as you go. Seeing the whole list — and where it contradicts itself — first is what stops the dictionary from baking in the same inconsistency it's meant to fix.
Define each metric — the plain meaning and the exact logic

For each metric, write two things: the sentence a non-analyst would understand, and the precise logic that computes it. Both matter — the sentence keeps the team honest, the logic makes it reproducible.

you ask

For each metric in the inventory, draft a dictionary entry with: a one-sentence plain-English definition anyone could read; the exact computation (the columns, the filter, the aggregation — e.g. distinct users with at least one login event in the calendar month); and the grain (per user, per account, per day). Where two definitions conflict, propose the one you'd standardize on and say why.

what you get back A first-draft entry per metric — plain meaning, exact logic, grain — with a recommended resolution for each conflict. You now have something concrete to ratify instead of an argument to keep having.
Pin the edge cases that quietly change the number

Most metric disputes aren't about the headline — they're about the edges nobody specified. Timezone, deduplication, what's excluded, how nulls are treated. Force each one onto the page.

you ask

For each metric, make the silent decisions explicit: which timezone defines the day/month boundary; whether we deduplicate and on what key; what's excluded (test accounts, internal users, refunds, $0 orders); and how nulls and late-arriving data are handled. List any edge case where you had to guess our intent, so I can decide it rather than you.

what you get back An edge-case block under each metric — "month = calendar month in UTC; excludes internal domains and test_account=true; refunds net out in revenue; null plan rows excluded and counted separately" — and a short list of decisions flagged for you, the human, to make.

The flagged guesses are the highest-value output. An edge case Claude had to assume is exactly the one two analysts would otherwise resolve differently.
Assign an owner and a source of truth per metric

A definition with no owner drifts back into chaos within a quarter. Name a person who can answer for each metric and the system that is its source of truth, so changes go through a person, not by accident.

you ask

For each metric, add an owner (the role who answers for it and approves changes to its definition) and the system of record it's computed from (the table or the report that is authoritative). Flag any metric that has no clear owner or is computed from two sources that could disagree — those are governance gaps to close.

what you get back Every entry now carries an owner and a source of truth, with the orphaned or dual-sourced metrics flagged — the governance gaps named so they can be assigned, not left to drift.
Assemble the one-page metrics.md every artifact cites

Pull it into one canonical file, ordered and skimmable. Keep it tight — a dictionary nobody can hold in their head doesn't get cited. This file is what every query comment, chart caption, and report points back to.

you ask

Assemble everything into one metrics.md: a short intro on how to use it, then one entry per metric with plain definition, exact logic, grain, edge cases, owner, and source of truth. Add a one-line changelog convention at the top (date, metric, what changed, who approved). Keep each entry to a few lines so the whole thing stays scannable.

what you get back A single, paste-ready metrics.md — the source of truth every query, chart, and report inherits, with a changelog so a definition can only change deliberately and on the record.

Save this file at the root of your analysis folder. From here on, every other Data playbook's 'how do you define active?' question has one answer: point at metrics.md.

make it your own

Hand it to every query: the dictionary's logic block drops straight into Write the query and learn the SQL — paste the definition in as the query's comment so the number is reproducible by someone who wasn't in the room (see the Systems playbooks).
Bilingual metric names: if you report in Arabic and English, add the Arabic name and one-line definition beside each metric so a bilingual board reads the same meaning in either language — author the Arabic definition in Arabic, don't translate the English one word-for-word.
Make it a skill (Power Track): load metrics.md as a reusable skill or a /define command (see the Features tab) so every analysis is checked against the agreed definitions automatically, not from memory.
Refresh on real change only: re-run this when a metric genuinely changes — a new exclusion, a redefinition — and bump the changelog. A definition that silently goes stale is worse than none, because everyone still trusts it.

watch out for

A definition with no owner drifts. The whole value is one source of truth; if everyone can edit it, within a quarter you're back to three numbers for 'active'. One owner per metric, changes are reviewed and logged — treat the file like the controlled document it is, not a wiki anyone can quietly 'improve'.
"Looks reasonable" is not "agreed". Claude can draft a definition, but the team has to ratify it — especially the conflict resolutions. An undisputed-because-unread dictionary is a disagreement waiting to resurface in front of a stakeholder.
The dictionary governs meaning, not correctness. It makes everyone count the same thing; it doesn't guarantee the underlying data is right — you still reconcile every result against a known total. Consistent and wrong is still wrong.
Pin the edges or the dictionary leaks. Two analysts will agree on 'active users' and still get different numbers if one drops test accounts and the other doesn't. The timezone/dedup/exclusion block is what makes the definition actually reproducible.

you'll end up with A one-page `metrics.md` — every reported metric with a plain meaning, exact logic, edge cases, an owner, and a source of truth — that every query, chart, and report inherits, so the whole organization finally agrees on what its numbers mean and stops reconciling definitions in meetings.

Questions people ask

How is a metric dictionary different from just writing good queries?: A query computes a number; a metric dictionary decides what the number is *supposed* to mean before anyone writes a query. Without it, two correct queries can return two different 'active users' because they encode two unstated definitions. The dictionary is the agreed definition every query then cites — it's what makes numbers reproducible and comparable across people and months, not just runnable.
Who should own the metric dictionary?: One owner per metric — usually the analyst or analytics lead closest to it — plus one overall owner for the file. The whole value is that it's a single source of truth; if everyone can edit it freely, it drifts back into the inconsistency it was meant to fix. Treat a definition change as a reviewed, logged update with an approver, not a free-for-all, and re-run the playbook only when a metric genuinely changes.
What do I need before I start?: A recent dashboard, board deck, or weekly report so you can list every metric you actually publish, plus the queries or spreadsheets behind a few of them so Claude can read what each number currently computes. Bring any standing disputes too — 'we never agree on churn' is exactly the kind of conflict this playbook is built to resolve on the page.
Does the dictionary guarantee our numbers are correct?: No — it guarantees they're *consistent*, which is different. The dictionary makes everyone count the same thing the same way; it doesn't certify the underlying data is clean or the logic is bug-free. You still reconcile every result against a known total and audit the source data. Consistent-and-wrong is still wrong; the dictionary just removes the second, avoidable failure of consistent-and-disagreeing.