Generate Metric Definition Documents

This skill creates comprehensive metric definition documents for business intelligence systems, standardizing metric documentation so business stakeholders and technical implementers stay aligned. Every definition must include a clear unique metric name, its business purpose, a precise technical definition/calculation methodology, all underlying data sources, business and technical ownership, and governance (approval status, review cycle, change management). Clarity guidance: use language both business and technical readers understand, avoid undefined jargon, spell out edge cases and exclusions explicitly, and include a worked example calculation.

Use it when a metric needs a governed, versioned definition that business and data teams both sign off on - not a one-line description buried in a dashboard tooltip.

SELECT
  DATE_TRUNC('month', order_date) as month,
  SUM(order_total) as monthly_revenue
FROM orders
WHERE order_status = 'completed'
GROUP BY 1

The document template covers an Overview block (Metric ID, category, business and technical owner, status), Business Context (purpose, key questions the metric answers), a Technical Definition with the exact SQL formula plus explicit inclusion/exclusion/filter/time-zone/currency business rules, a Data Sources table naming tables, columns, refresh frequency, and owner, and Dimensions and Granularity (time, geography, product, customer breakdowns down to the lowest grain). Quality and Validation specifies range, completeness, and cross-metric consistency checks and a worked sample calculation (three input rows totaling $225.50 after excluding a cancelled order). Change Management defines a four-step approval process (business owner review, technical validation, a 5-business-day stakeholder review period, final sign-off) plus a version history table. Common patterns are given as reusable formula templates for ratio metrics (with an explicit divide-by-zero rule), period-over-period and percentage-change comparisons, and cohort-analysis metrics (cohort definition, time buckets, survivorship bias handling).

Analytics engineers and BI teams who need a standardized, governed metric definition template rather than inconsistent tribal-knowledge descriptions scattered across dashboards. Naming conventions call for descriptive business-friendly names with the time period included when relevant ("Monthly Active Users" not "Active Users") and consistent prefixes for related metrics. Common pitfalls are named explicitly: ambiguous time-zone handling, inconsistent null-value treatment, missing exclusion criteria, undefined aggregation methods, no historical-consistency rules, insufficient stakeholder review, and missing data-lineage documentation - all addressed by running definition workshops, maintaining glossaries, running quarterly review cycles, and certifying metrics through automated data-quality checks. Quality assurance goes further than the checks themselves: it also means actively monitoring metric usage and adoption once published, and tracking and resolving definition disputes quickly before conflicting numbers erode trust in the metric.