semantic-layer-change-review · diff
git:20260502.5f165cc to git:20260605.f27d14b
60 added, 15 removed. Audit A to A.
---
name: semantic-layer-change-review
- description: "Use when modifying dbt metrics or semantic models to ensure mathematical correctness and backwards compatibility."
+ description: Use when a change touches dbt semantic models, metrics, saved queries, or other semantic-layer YAML -- especially when an existing metric's expression, aggregation, filters, or dimensions are modified.
---
- # Semantic Layer Change Review
+ ## Purpose
- Changes to the semantic layer directly impact dashboards and business reporting. A silent drift in a metric definition destroys trust.
+ Changes to the semantic layer directly impact dashboards and business reporting. A silent drift in a metric definition destroys trust. Review every semantic-layer change for mathematical soundness and backwards compatibility before approval.
- ## Review Protocol
+ ## When to Use
- 1. **Identify the Change Type**:
- - **Addition**: Safe. (Adding a new metric or dimension).
- - **Deprecation**: Requires communication. (Removing a metric).
- - **Modification**: High Risk. (Changing the SQL expression, aggregation, or filters of an existing metric).
+ - A PR modifies metric or semantic model YAML
+ - A metric's `expr`, aggregation, or filters are changing
+ - New dimensions or entities are being added to an existing semantic model
- 2. **Evaluate Mathematical Soundness**:
+ ## Inputs
+
+ - The semantic-layer diff (semantic models, metrics, saved queries)
+ - The underlying model's grain and entity keys
+
+ ## Workflow
+
+ 1. **Enumerate what changed:**
+
+ ```bash
+ git diff origin/main...HEAD -- '*.yml' '*.yaml'
+ dbt ls --resource-type metric
+ dbt ls --resource-type semantic_model
+ ```
+
+ 2. **Identify the change type:**
+ - **Addition** — safe (adding a new metric or dimension).
+ - **Deprecation** — requires communication (removing a metric).
+ - **Modification** — high risk (changing the SQL expression, aggregation, or filters of an existing metric).
+
+ 3. **Evaluate mathematical soundness:**
- Are we averaging an average?
- Are we summing a distinct count?
- Does adding this dimension cause a fan-out that inflates the metric?
- 3. **Check Backwards Compatibility**:
- - If an existing metric's logic is changed, you MUST flag it. The recommended path is to use dbt's metric versioning or create a new metric (e.g., `revenue_v2`) rather than silently altering historical numbers.
+ 4. **Check backwards compatibility.** If an existing metric's logic is changed, you MUST flag it. The recommended path is dbt's metric versioning or a new metric (e.g., `revenue_v2`) rather than silently altering historical numbers. Find consumers of the metric before judging impact:
- 4. **Verify Entity Mapping**:
- - Ensure `entities` (primary/foreign keys) match the granularity of the underlying semantic model.
+ ```bash
+ grep -rn "<metric_name>" --include="*.yml" --include="*.yaml" .
+ ```
- ## Anti-Pattern
- Do not approve a pull request that changes the `expr` of a core metric without explicitly confirming the business requested the restatement of historical data.
+ 5. **Verify entity mapping.** Ensure `entities` (primary/foreign keys) match the granularity of the underlying semantic model.
+
+ 6. **Confirm definitions still parse:**
+
+ ```bash
+ dbt parse
+ ```
+
+ ## Output
+
+ - Change classification (addition / deprecation / modification) per touched metric or semantic model
+ - Mathematical soundness findings
+ - Backwards-compatibility verdict, with consumers that need communication
+ - Entity/grain mismatches, if any
+
+ ## Verification
+
+ - [ ] Every touched metric and semantic model classified by change type
+ - [ ] Modifications to existing metrics explicitly flagged, never silently approved
+ - [ ] Consumers of modified metrics identified
+ - [ ] `dbt parse` passes on the changed project
+ - [ ] Entity keys checked against the underlying model's grain
+
+ ## Failure Modes
+
+ - **Silent restatement** — approving a change to a core metric's `expr` without explicitly confirming the business requested the restatement of historical data.
+ - **Treating modification like addition** — additions are safe; modifications are high risk and need versioning or a new metric.
+ - **Fan-out blindness** — a new dimension join can inflate a metric while every individual definition still looks correct.