Brainforge Knowledge

metrics-definition-doc-template

4 min read

Metrics Definition Document — Template

About this document (Brainforge)

Internal conventions for how this file works in the repo. Strip or export without this section when sharing a client-only artifact.

Titling and filename

Use Metrics Definition: [Metric Name] for the document title. Example: Metrics Definition: Monthly Recurring Revenue.

Filename: {client}-metric-{metric-slug}.md under knowledge/clients/{client}/resources/metrics/.

When to use this template

Use this when formalizing the definition of a business metric: what it means, how it is calculated, which table it lives in, what is excluded, and who owns it. This document is the single source of truth for a metric and is used to resolve disagreements when different teams calculate the same metric differently.

Create one file per metric (or per tightly related group of metrics).

Common triggers for creating this document:

  • A metric is referenced in multiple dashboards with different values
  • A new metric is being introduced for the first time
  • A client asks “how is this calculated?” and the answer is not written down anywhere
  • Brainforge is handing off a model to a client and needs to document what it produces

Do not use this template when:

  • documenting a data quality investigation (use the Data Findings Memo)
  • describing the entire data platform architecture (use the Warehouse Architecture Assessment)

Metrics Definition: [Metric Name]

Owner: [Person or team responsible for maintaining this definition] Last updated: YYYY-MM-DD Status: [Draft / Approved / Deprecated] Source table: [SCHEMA.TABLE_NAME]

ArtifactLink / pathNotes
Data Platform Documentation (Core Metrics)[Google Sheet link]Source catalog; this file and the sheet must match
Discovery Memo[path to A1 memo]Source profiling reference
Dashboard Specification[path if applicable]Dashboard this metric feeds into

Business Definition

[1–2 sentences. What does this metric mean to the business? Write it as a non-technical person would understand it. Avoid SQL, table names, or acronyms in this section.]

Example: “Monthly Recurring Revenue (MRR) is the normalized monthly value of all active subscription revenue. It represents what a company earns each month from customers on recurring plans, excluding one-time purchases.”

Why This Metric Matters

[Optional but recommended. 1–3 sentences on what decisions this metric informs and who uses it. This section helps new team members understand why the metric exists.]

Technical Definition

Formula:

[Plain-language formula, e.g.: MRR = invoice net amount / (billing_interval_count × months_per_interval)]

SQL:

-- [Description of what this query computes]
select
    [dimension columns],
    [metric calculation] as [metric_name]
from [source_table]
where [key filters]

Grain: [One row per what? e.g., “one row per customer per month”]

Time dimension: [Which date field drives the time dimension? e.g., “period_month = date_trunc(‘month’, invoice_date)“]

What Is Included

[Explicit list of what goes into this metric. Be specific.]

  • [Item] — [Why included]
  • [Item] — […]

What Is Excluded

[Explicit list of exclusions. This is often where disagreements live. Be specific about both what is excluded and why.]

  • [Item] — [Why excluded. If this was a deliberate business decision rather than a technical constraint, note who made the decision and when.]
  • [Item] — […]

Edge Cases and Known Limitations

[Be honest about where the metric is approximate or where edge cases exist. One bullet per item.]

  • [Edge case] — [What happens in this case. How it is handled. Whether the handling is ideal or a known approximation.]
  • [Limitation] — [What the metric cannot answer. What question a user might ask that this metric would answer incorrectly.]

Calculation Example

[Walk through a concrete example. Use realistic but anonymized numbers. Show the inputs and the output clearly.]

Input:

  • Customer: [Name or ID]
  • Invoice amount: $[X]
  • Billing interval: [monthly / annual / etc.]

Calculation:

[Step-by-step walkthrough of the formula]

Output: MRR = $[Y]

[Metrics that are closely related or commonly confused with this one. One bullet per related metric, with a brief note on the distinction.]

  • [Metric name] — [How it differs from this metric or how they relate.]
  • [Metric name] — […]

Change Log

[Track meaningful changes to the definition. New entries at the top.]

DateAuthorChange
YYYY-MM-DD[Name][Description of what changed and why]

Appendix: Pre-handoff QA Checklist

  • Business definition is readable by a non-technical stakeholder
  • Technical formula and SQL agree (run the SQL to verify)
  • Inclusion and exclusion lists are specific enough to resolve disputes
  • Edge cases and known limitations are documented honestly
  • Calculation example uses realistic numbers and matches the formula
  • Change log is present and the latest entry matches the last-updated date

Graph View