---
name: metric-definition-document
description: "A metric definition document with the exact calculation, edge-case rules, and a worked example, so two teams asking the same question get the same number. Use when two teams report different numbers for the same metric and need one agreed, written definition. Do not use for building the dashboard or pipeline that computes the metric. Related topics: Data, Reporting, Communication."
---

# Metric Definition Document

A metric definition document with the exact calculation, edge-case rules, and a worked example, so two teams asking the same question get the same number.

## When to use

Use this skill when two teams report different numbers for the same metric and need one agreed, written definition. Do not use it for building the dashboard or pipeline that computes the metric.

## Workflow

1. Ask the user for each input listed below in a single message, skipping any they have already given. Where options are listed, offer them, but accept other answers too.
2. State the business question the metric answers and the decisions it drives.
3. Write the exact calculation with inclusions, exclusions, time grain, and the source of truth.
4. Trace each reported disagreement to the edge case behind it, done when every gap has a named cause.
5. Set an explicit rule for refunds, test accounts, timezones, deleted records, and late data.
6. Add what the metric does not measure, a worked example, and the owner of future changes.

## Inputs

- **Metric name** (free text, e.g. "What people call it")
- **What it is meant to measure** (longer free text)
- **How it is calculated now** (longer free text)
- **Sources** (longer free text)
- **Where the numbers disagree** (longer free text)
- **Who uses it and for what** (longer free text)

## Output

A definition document with calculation, scope rules, edge-case table, limits of use, a worked numeric example, and an owner.

## Prompt template

Fill the inputs into this template and follow it as the full instruction.

### Metric Definition

Write the definition for the metric below.

- Metric name: {{Metric name}}
- What it is meant to measure: {{What it is meant to measure}}
- How it is calculated now: {{How it is calculated now}}
- Sources: {{Sources}}
- Where the numbers disagree: {{Where the numbers disagree}}
- Who uses it and for what: {{Who uses it and for what}}

Write the definition: exact calculation, what is included and excluded, the time grain, and the source of truth.

Spend most of the effort on the edge cases that cause the disagreements: refunds, test accounts, timezones, soft-deleted records, and late-arriving data. That is where the differences come from. Trace each reported disagreement to the rule that explains it.

State what the metric does not measure, since misuse causes more damage than miscalculation. Add a worked example with real numbers and name who owns changes to this definition.

## Pitfalls

- Defining the formula but not the edge cases, which leaves the original disagreement in place.
- Naming a source of truth that teams cannot actually query.
- Omitting a change owner, so the definition drifts again within a quarter.
