| name | des-semantic-model-design |
| description | Use when designing semantic models, metrics layers, measures, dimensions, hierarchies, relationships, trust status, freshness/quality visibility, and business-friendly data consumption. |
des-semantic-model-design
Purpose
Use this skill to create and validate the Semantic Model Specification for any data engineering project.
This skill defines how trusted Gold outputs are exposed to business users, analysts, BI tools, metrics layers, dashboards, AI agents, or applications through business-friendly semantic concepts.
It covers semantic entities, measures, dimensions, hierarchies, relationships, metric definitions, calculation ownership, naming conventions, filters, security, certification, lineage, usage rules, freshness visibility, quality visibility, and consumer-facing meaning.
The goal is to prevent inconsistent metrics, ambiguous business terms, unsafe joins, unclear dimensions, hidden quality risk, and dashboard-level metric duplication.
Semantic Model Design should answer:
Which business concepts are exposed?
Which Gold outputs feed them?
Which measures are certified?
Which dimensions can slice them?
How do entities relate?
At what grain do measures aggregate?
Who owns calculations?
Who can access rows/columns/measures?
How should freshness and quality be shown to users?
Which semantic objects are Draft, Promoted, Certified, Risk, Blocked, or Deprecated?
In the Phase-Orchestrated Support Model, this phase is not Done when the Semantic Model Specification is first written.
Phase 16 is Done only when:
Semantic Model Specification exists
+ Phase 15 artifact and handoff are reviewed
+ semantic validation work is identified
+ semantic evidence is collected or waived with reason
+ artifact is revised from evidence
+ Phase 16 Done Gate passes
+ Phase 16 to Phase 17 handoff exists
When To Use
Use this skill when:
- Phase 15 Orchestration and Observability Specification exists;
- Phase 15 handoff exists or the user explicitly accepts the risk of continuing without it;
- Gold outputs are ready or planned for BI, semantic layer, dashboarding, analytics, AI agents, or self-service consumption;
- business users need friendly terms instead of physical table/column names;
- metrics and KPIs need consistent exposure;
- slicing/filtering dimensions need approval;
- semantic relationships and join behavior need clarity;
- row-level, column-level, object-level, or measure-level security affects consumption;
- freshness/quality status should be visible to consumers;
- the workflow router selects Phase 16.
Do not use this skill to build dashboards, write DAX/LookML/SQL/Cube/dbt semantic code, create BI visuals, implement APIs, deploy semantic models, create CI/CD workflows, or create Power BI/Looker/Cube implementation artifacts.
Allowed in this phase:
semantic scope design
semantic model inventory
consumer/use-case mapping
Gold-to-semantic mapping
business glossary alignment
semantic entity design
measure/KPI semantic design
dimension/attribute design
hierarchy design
relationship/join behavior design
grain/aggregation behavior design
filter/slicer design
time intelligence expectation design
calculation ownership design
naming/display convention design
security/access model design
certification/trust status design
freshness/quality display expectation design
lineage/metadata expectation design
semantic testing expectation design
Required Inputs
The agent should look for:
_des-output/planning-artifacts/01-business-discovery-brief.md;_des-output/planning-artifacts/02-business-question-catalog.md;_des-output/planning-artifacts/03-requirements-and-kpi-catalog.md;_des-output/planning-artifacts/04-data-product-specification.md;_des-output/planning-artifacts/06-conceptual-domain-model.md;_des-output/planning-artifacts/10-silver-layer-specification.md;_des-output/planning-artifacts/11-gold-layer-specification.md;_des-output/planning-artifacts/12-data-contract-specification.md;_des-output/planning-artifacts/13-transformation-specification.md;_des-output/planning-artifacts/14-data-quality-specification.md;_des-output/planning-artifacts/15-orchestration-observability-specification.md;_des-output/phase-handoffs/phase-15-to-16-handoff.md;_des-output/evidence/phase-15/phase-15-evidence-pack.md, if available;_des-output/implementation-artifacts/phase-15-done-gate.md, if available;- workflow status file, if present;
- approved KPIs and metric definitions;
- Gold datasets and grain;
- Gold quality and freshness expectations;
- semantic/BI serving direction;
- consumers and personas;
- access/security requirements;
- glossary/domain concepts.
If the Gold Layer Specification, KPI definitions, or Phase 15 handoff are missing or too weak, stop and ask whether to route back to the owning phase.
Output Files
Create or update the configured main output file:
_des-output/planning-artifacts/16-semantic-model-specification.md
Also create or update the Phase-Orchestrated Support outputs when using validated phase delivery:
_des-output/phase-support-plans/phase-16-support-plan.md
_des-output/evidence/phase-16/phase-16-evidence-pack.md
_des-output/implementation-artifacts/phase-16-artifact-revision.md
_des-output/implementation-artifacts/phase-16-done-gate.md
_des-output/phase-handoffs/phase-16-to-17-handoff.md
The main artifact must capture:
- semantic model summary;
- semantic scope;
- semantic non-scope;
- semantic design principles;
- semantic model inventory;
- consumer and use-case mapping;
- Gold-to-semantic mapping;
- business glossary alignment;
- semantic entities;
- measures and KPIs;
- dimensions and attributes;
- hierarchies;
- relationships and join behavior;
- grain and aggregation behavior;
- filters and slicers;
- time intelligence expectations;
- calculation ownership;
- naming and display conventions;
- security and access model;
- certification and trust status;
- freshness and quality display expectations;
- lineage and metadata expectations;
- semantic testing expectations;
- semantic evidence summary;
- risks;
- assumptions;
- open questions;
- Phase 16 evidence summary;
- Phase 16 handoff notes;
- next skill recommendation.
On Activation
-
Read this SKILL.md completely.
-
Read customize.toml.
-
Identify output_file, template_file, checklist_file, status_file, and required upstream artifacts.
-
Identify Phase-Orchestrated Support files:
phase_support_plan_file;phase_evidence_pack_file;phase_artifact_revision_file;phase_done_gate_file;phase_handoff_file.
-
Load only steps/step-01-context-and-readiness.md.
-
Do not load step-02 or step-03 until the current step explicitly instructs you to continue.
-
Stop at every HALT point and wait for user input.
-
Do not invent metric formulas, business terms, relationships, hierarchies, security rules, certified status, ownership, or trust claims.
-
Do not write DAX, SQL, LookML, Cube, dbt semantic model, Power BI model, dashboard, API, CI/CD, deployment, or implementation code.
-
Before marking Phase 16 as Done, create or update the support plan, evidence pack, artifact revision notes, Done Gate, handoff, and workflow status.
Process Overview
The detailed execution procedure lives in steps/.
At a high level, this skill will:
- Confirm upstream transformation, contract, Gold, Silver, Bronze, and requirement context.
- Confirm Phase 15 handoff readiness.
- Identify datasets and outputs requiring quality rules.
- Define data quality dimensions and rule categories.
- Map rules to datasets, contracts, transformations, and layers.
- Define thresholds, severity, failure handling, and quality gates.
- Define evidence, reporting, ownership, and monitoring expectations.
- Ask HALT questions for unresolved quality decisions.
- Draft the Data Quality Specification.
- Create the Phase 14 Support Plan.
- Collect or reference Phase 14 evidence.
- Revise the Data Quality Specification using evidence.
- Run the Phase 14 Done Gate.
- Create the Phase 14 to Phase 15 Handoff.
- Update workflow status.
- Recommend the next skill.
Do not execute this overview directly. Follow the step files.
Phase-Orchestrated Support Model
Phase 16 uses semantic validation support work.
The purpose is not BI implementation. The purpose is to make metrics, dimensions, relationships, access, and trust status business-safe before serving-layer design.
Required Support Work
| Support Work | Purpose | Output |
|---|
| Phase 15 Handoff Review | Check semantic design follows operational trust/freshness constraints. | Evidence pack section |
| Semantic Scope Check | Validate semantic model boundary. | Evidence pack section |
| Consumer/Use-Case Mapping Check | Ensure semantic model exists for real users. | Evidence pack section |
| Gold-to-Semantic Mapping Check | Ensure semantic objects trace to trusted Gold outputs. | Evidence pack section |
| Business Glossary Alignment Check | Avoid term ambiguity and synonym drift. | Evidence pack section |
| Semantic Entity Check | Validate exposed business entities. | Evidence pack section |
| Measure/KPI Definition Check | Prevent metric drift from Phase 03/11. | Evidence pack section |
| Dimension/Attribute Check | Validate slicing/filtering objects. | Evidence pack section |
| Hierarchy Check | Validate drill paths. | Evidence pack section |
| Relationship/Join Behavior Check | Prevent double counting and ambiguous joins. | Evidence pack section |
| Grain/Aggregation Behavior Check | Validate measure calculation behavior. | Evidence pack section |
| Filter/Slicer Check | Validate user analysis paths. | Evidence pack section |
| Time Intelligence Check | Validate date/calendar/as-of behavior. | Evidence pack section |
| Calculation Ownership Check | Make measure ownership accountable. | Evidence pack section |
| Naming/Display Convention Check | Ensure business-friendly semantic UX. | Evidence pack section |
| Security/Access Model Check | Validate RLS/CLS/object/measure access needs. | Evidence pack section |
| Certification/Trust Status Check | Prevent false Certified labels. | Evidence pack section |
| Freshness/Quality Display Check | Ensure consumers see data trust signals. | Evidence pack section |
| Lineage/Metadata Check | Enable audit/debug and AI-agent explainability. | Evidence pack section |
| Semantic Testing Expectation Check | Prepare validation for later implementation. | Evidence pack section |
| Contract/Quality Alignment Check | Ensure exposed objects are protected by contracts and quality rules. | Evidence pack section |
| Phase 16 Done Gate | Decide whether Phase 16 is Done, Done with risks, or Blocked. | phase-16-done-gate.md |
| Phase 16 Handoff | Tell Phase 17 what serving layer can expose. | phase-16-to-17-handoff.md |
HALT Policy
This skill must stop when a required decision cannot be safely inferred.
Stop especially when:
- upstream contexts are unknown;
- required inputs are missing.
Detailed HALT checkpoints are defined in steps/.
Guardrails
The agent must not:
- define metrics differently from Phase 03 or Phase 11;
- expose ambiguous metrics without status or warning;
- hide grain or aggregation behavior;
- create relationships that cause double counting without warning;
- expose technical names directly when business-friendly naming is needed;
- assume row-level, column-level, object-level, or measure-level security rules;
- mark a semantic model Certified unless quality, ownership, lineage, contract, freshness, and operational expectations support it;
- hide quality/freshness/trust status from consumers where it matters;
- design dashboard visuals in this phase;
- implement semantic model code in this phase;
- mark Phase 16 Done if P1 semantic objects lack Gold mapping, KPI alignment, ownership, trust status, security, freshness/quality visibility, or evidence.
Handoff To The Next Skill
Recommend des-serving-layer-design only after:
Semantic Model Specification exists
+ Phase 16 support plan exists or is waived with reason
+ Phase 16 evidence pack exists or evidence is waived with reason
+ Phase 16 Done Gate is Pass or Pass with risks
+ Phase 16 to Phase 17 handoff is Ready or Ready with Risks
If the phase is Draft or Blocked, recommend one of:
continue des-semantic-model-design
return to Step 02 semantic concepts, measures, and relationships
resolve HALT question
route back to des-gold-layer-design
route back to des-requirements-and-kpis
route back to des-data-contracts
route back to des-data-quality
des-wise
des-correct-course
