Metric definition spec that removes ambiguity before you build a dashboard
Turns a loosely named metric ("active users", "churn", "time to resolution") into a precise definition: formula, inclusions, exclusions, time window, edge cases, owner and known pitfalls, ready for a data team to implement.
Prompt in Data by AISkillHub Library
What it does
Two teams reporting different numbers for "active users" is usually a definition problem, not a data problem. This prompt takes a metric name and the business question behind it and produces a one-page definition spec that a data analyst or engineer can implement consistently, and that a non-technical reader can understand.
**Use it when** you are adding a metric to a dashboard or OKR, you have inherited a metric nobody can explain, or two reports disagree.
**What you get** - A plain-language definition in one or two sentences. - The precise formula, with numerator, denominator and unit. - The grain (per user, per account, per ticket) and the time window and timezone. - Inclusion and exclusion rules (test accounts, internal users, refunds, reopened tickets and so on). - Edge cases, each with a decision or a question for the metric owner. - Data sources described in terms of the events or fields you list. - Known pitfalls and how the metric could be gamed or misread. - Related metrics that should be read alongside it. - A short list of decisions you still need to make.
**What it will not do** - It will not assume your table or event names. If you provide them, it uses them; otherwise it describes the data needed in plain terms. - It will not choose business rules for you when they matter (for example, whether a paused subscription counts as churned). It lists options and the trade-off, and marks the item as a decision. - It does not write SQL. Once the spec is agreed, any analyst can implement it in your own stack.
How to use it
## How to use
1. Open `prompts/metric-definition-spec.md` and copy everything below the title line. 2. Replace each `{{variable}}` with your own content. Paste long material (notes, transcripts, tables) directly in place of the variable; keep the surrounding tags so the model can tell inputs apart. 3. Start a new chat in ChatGPT, Claude or Gemini and paste the filled prompt as your first message. 4. Read the output against the quality checks at the end of the prompt before you use or send it.
## Variables
- `{{metric_name}}`: the metric, e.g. `weekly active users`, `logo churn`, `first response time`. - `{{business_question}}`: what decision this metric informs, e.g. `are we retaining small customers after onboarding changes?`. - `{{available_data}}`: events, tables or fields you have, described in words or by name. Optional. - `{{current_definition}}`: how it is calculated today, if anywhere, or `none`. - `{{owner}}`: team or person accountable for the metric.
If you do not have a value for an optional variable, write `none` rather than deleting it, so the prompt still reads correctly.
## Reusing it
To reuse it often, save the prompt (with the variables left in) as the instructions of a Claude Project, a custom GPT or a Gemini Gem, then paste only the inputs in each new chat.
Files
Save each file at the path shown, relative to your project root.