--- name: define-versioned-metric-contracts-for-analytics-alignment description: 'Turn disputed or ambiguous business metrics into governed, testable semantic contracts with explicit grain, calculation rules, lineage, ownership, access constraints, and change-control expectations. Use when teams disagree on how a KPI is calculated, filtered, attributed, or time-bucketed. A dashboard, report, or semantic layer needs metric definitions that are testable and version controlled. A metric appears in multiple tools with conflicting results or unclear lineage. A new or revised KPI needs ownership, access rules, acceptance checks, and migration guidance before adoption.' compatibility: 'Instruction-only Agent Skill. Requires an Agent Skills-compatible client and access to the tools or systems named in the instructions. No executable scripts are bundled.' metadata: publisher: RichlyAI product: Amo.ng amo_id: AMO-S-000031 canonical_url: 'https://amo.ng/skills/define-versioned-metric-contracts-for-analytics-alignment' package_version: 1.0.0 source_type: prompt source_amo_id: AMO-P-000263 source_content_sha256: 5c94f8a8c8489e1f90be83d91ab454c02f11e29cbc137eb52150d872d7080594 source_version: 1.0.0 --- # Define Versioned Metric Contracts for Analytics Alignment ## When to use this Skill - Teams disagree on how a KPI is calculated, filtered, attributed, or time-bucketed. - A dashboard, report, or semantic layer needs metric definitions that are testable and version controlled. - A metric appears in multiple tools with conflicting results or unclear lineage. - A new or revised KPI needs ownership, access rules, acceptance checks, and migration guidance before adoption. ## When not to use this Skill - Do not use as a substitute for executing SQL reconciliation or validating raw data quality when the issue is primarily data corruption. - Do not use for a one-off chart request where metric definitions are already stable and governed. - Do not use to make final financial, regulatory, board, or compensation decisions without human review of evidence and calculations. - Do not use when the metric owner, intended decision, or source systems are unknown; clarify those first. ## Required inputs - Metric name, business purpose, and decisions the metric will support. - Current definitions, formulas, dashboard references, SQL snippets, semantic-layer definitions, or documentation. - Source systems, tables, fields, data grain, refresh cadence, and known lineage. - Time logic, filters, exclusions, attribution rules, segmentation rules, and currency or timezone handling where applicable. - Known discrepancies, stakeholder disputes, downstream reports, and affected audiences. - Required governance constraints, owners, approvers, access restrictions, and change-management expectations. - Authoritative metric owner and approvers, current contract version, compatible producer and consumer versions, lineage evidence, and downstream change owners. Use [INPUT-TEMPLATE.md](assets/INPUT-TEMPLATE.md) to organize the supplied information. ## Required tools or access Published source tool designations: Claude. These are source designations, not portable-client compatibility claims. Use only authorized access described in the inputs and source instructions. Do not claim access or inspection without evidence. ## Procedure Before starting, read [SOURCE.md](references/SOURCE.md), including the exact Prompt instructions and any ordered Workflow steps, review notes and carry-forward requirements. 1. Use the linked source prompt AMO-P-000263 as the contract-design scaffold; apply its structure to the supplied metric context without reproducing the entire source. 2. Identify the metric’s intended decision use and the risks of inconsistent interpretation. 3. Separate supplied definitions from assumptions, inferred business rules, missing lineage, and unresolved stakeholder decisions. 4. Define the metric contract: name, description, grain, entities, calculation, time window, eligibility rules, exclusions, dimensions, source lineage, freshness expectations, and permitted uses. 5. Specify validation checks such as reconciliation queries, row-count checks, aggregate comparisons, edge-case examples, dashboard parity tests, and acceptance thresholds. 6. Document the authoritative metric owner, contract version, producer and consumer compatibility, lineage evidence, approval workflow, downstream impact, deprecation or migration path, and communication requirements for metric changes. 7. Flag access-control, privacy, compensation, finance, compliance, or executive-reporting implications for appropriate human review. 8. Avoid overstating readiness; provide a status such as ready, ready with conditions, needs reconciliation, or blocked by missing evidence. Published expected output: A metric contract package containing the agreed definition, lineage map, validation checklist, governance owners, versioning and migration rules, unresolved questions, and a decision-use readiness status. ## Review gates Read and apply the source review instructions in [SOURCE.md](references/SOURCE.md) before acting. Keep proposed, unrun and executed actions distinct; preserve missing evidence and obtain the human approvals required by the source. ## Completion criteria Complete when: - The metric definition includes grain, calculation, filters, time logic, dimensions, and source lineage. - All disputed assumptions and unresolved decisions are listed with owners or follow-up questions. - Validation checks are concrete enough for an analyst or analytics engineer to implement. - Permitted and non-permitted uses are explicit. - The readiness status is supported by the supplied evidence and does not exceed it. - Downstream changes identify affected owners, compatibility conditions, validation evidence, and explicit approval before adoption. Use the [completion checklist](references/COMPLETION-CHECKLIST.md) and record unresolved items. ## Limitations - Do not invent source-system schemas, formulas, stakeholder agreements, or reconciliation results. - Do not present a metric as authoritative until its owner and validation evidence are supplied or explicitly approved. - Keep business recommendations separate from approval authority. - Preserve uncertainty around ambiguous data grain, time logic, attribution, or exclusions. - Require human review for financial reporting, investor reporting, compensation, compliance, or other consequential metric use. This is an instruction-only package. Packaging does not execute work, grant access or independently verify the package. Existing public verification in amo.json describes only the identified published source resources. ## References - [Published source instructions](references/SOURCE.md) - [Completion checklist](references/COMPLETION-CHECKLIST.md) - [Input template](assets/INPUT-TEMPLATE.md) - [Rights](RIGHTS.md) - [Canonical Amo.ng Skill](https://amo.ng/skills/define-versioned-metric-contracts-for-analytics-alignment)