---
name: domain-review
description: Use this skill when the user asks to review, audit, validate, or quality-check an existing MD-DDL domain and its detail files. Also use before declaring a domain “complete” or production-ready. This skill performs both structural conformance checks and decision-quality checks for relationship granularity, temporal tracking, existence, mutability, conceptual-to-logical realization, standards alignment, and regulatory posture.
---

# Skill: Domain Review

Covers full-domain review of MD-DDL artifacts with two goals:
1) structural correctness against the MD-DDL specification, and
2) modelling decision quality against cross-skill guidance and standards/regulatory expectations.

**This is a contextual quality review, not a lint pass.** The review protocol below identifies structural breakages and decision-quality issues — it does not reject files for convention deviations, vocabulary differences, or organisational adaptations. See `md-ddl-specification/1-Foundation.md` "Validation Model" for the normative definition of what is and is not mechanically enforced.

**On vocabulary deviations:** If the domain uses non-standard field names or vocabulary (e.g., `phi` instead of `pii`, `data_class` instead of `classification`), note this as an **observation** with the flag "potential spec vocabulary gap" — do not flag it as a structural error or non-conformance. The deviation is signal about how the spec should evolve.

## References to Load

Load these references before performing the review:

- Domains spec: `md-ddl-specification/2-Domains.md`
	(reference stub: `../domain-scoping/references/domains-spec.md`)
- Entities spec: `md-ddl-specification/3-Entities.md`
	(reference stub: `../entity-modelling/references/entities-spec.md`)
- Enumerations spec: `md-ddl-specification/4-Enumerations.md`
	(reference stub: `../entity-modelling/references/enumerations-spec.md`)
- Relationships spec: `md-ddl-specification/5-Relationships.md`
	(reference stub: `../relationship-events/references/relationships-spec.md`)
- Events spec: `md-ddl-specification/6-Events.md`
	(reference stub: `../relationship-events/references/events-spec.md`)
- Sources spec: `md-ddl-specification/7-Sources.md`
	(reference stub: `../source-mapping/references/sources-spec.md`)
- Transformations spec: `md-ddl-specification/8-Transformations.md`
	(reference stub: `../source-mapping/references/transformations-spec.md`)
- Conceptual/physical realization: `../entity-modelling/conceptual-to-physical-realisation.md`
- Standards alignment: `../standards-alignment/SKILL.md`
- Regulatory compliance benchmark: `../../../agent-governance/skills/regulatory-compliance/SKILL.md`

If the domain is in a recognized industry (banking, payments, insurance, healthcare, telecom), standards and regulatory checks are mandatory, not optional.

---

## Review Protocol

Run this protocol in order. Do not skip sections.

### 1) Inventory and Coverage

Confirm all modeled artifacts are present and navigable:

- Domain file exists and includes Metadata, Diagram, and all four summary tables
- Every summary table Name link resolves to an existing detail file anchor
- Every referenced entity/enum/relationship/event appears exactly once in the expected section
- No orphaned detail files that are not represented in summary tables (unless explicitly marked draft)

### 2) Structural Conformance Review

Validate structure and formatting against MD-DDL spec:

- Heading hierarchy and section placement
- Mermaid syntax in diagrams; style conventions per `guides/diagram-style.md` (deviations are observations, not errors)
- Entity YAML completeness (identifier, attributes, no FK attributes)
- Enum declaration correctness (simple list vs dictionary usage)
- Relationship YAML completeness (`source`, `type`, `target`, `cardinality`, `granularity`, `ownership`)
- Event YAML completeness (`actor`, `entity`, `emitted_on`, `business_meaning`, temporal priority)
- Link integrity and anchor correctness

### 3) Decision-Quality Review (Non-Structural)

Assess modelling choices and explain *why* each is acceptable or needs revision.

#### Relationship Granularity

For each relationship, verify chosen `granularity` matches business meaning:

- `atomic` only when instance-level pairing is true
- `group` when one side is aggregate/collection semantics
- `period` when state-at-time semantics are intended

Flag cases where default `atomic` appears unexamined.

#### Entity Temporal Tracking

For each temporal entity, confirm tracking mode matches lifecycle and audit need:

- `valid_time`, `transaction_time`, `bitemporal`, or explicit none-by-design
- temporal attributes and constraints are coherent with narrative and governance

Flag missing or contradictory temporal strategy.

#### Existence

Validate `existence` (`independent` / `dependent` / `associative`) against conceptual meaning and expected physical realization.

Flag misuse driven by implementation shortcuts.

#### Mutability

Validate `mutability` choice against expected change behavior and lineage/audit requirements:

- `immutable`, `append_only`, `slowly_changing`, `frequently_changing`, `reference`

Flag choices that conflict with temporal requirements or event semantics.

#### Conceptual → Logical Realization

Using `conceptual-to-physical-realisation.md`, verify:

- source/ownership direction is coherent
- cardinality in detail files matches conceptual statements in domain file
- M:N patterns are modelled intentionally and not collapsed accidentally
- logical choices do not imply contradictory physical targets

Flag ownership/existence conflation and cardinality mismatches.

### 4) Standards Alignment Review

For each domain concept claiming a standard mapping:

- mapping is plausible and specific (not superficial name matching)
- reference links are valid and point to intended standard object
- material deviations from the standard are acknowledged in descriptions where needed

Flag fabricated, weak, or ambiguous mappings.

### 5) Regulatory Review

Assess domain and entity governance posture against stated jurisdictional scope:

- `regulatory_scope` matches domain geography and business context
- domain-level defaults are present and sensible
- entity-level governance overrides are used only where stricter or exceptional
- retention, classification, and access controls are not contradictory
- AML/CTF, privacy, and jurisdiction-specific obligations are represented where applicable

Flag under-specified regulatory posture and unsupported claims.

### 6) Source and Transform Review

If the domain declares source systems in `## Source Systems`, review the source layer:

#### Source File Conformance

- Each source system in the domain summary has a corresponding `sources/<system>/source.md` file
- Source files include platform, capability, and change model metadata
- Domain feed tables map every source table to a canonical entity
- Source schema tables are present with column-level detail
- `Destination` column uses correct formats (`Entity.Attribute` for direct, `[Name](#anchor)` for transforms)

#### Transform File Conformance

- Transform files follow `table_<source-table>.md` naming pattern
- Each transform has a level-3 heading, prose description, and YAML block
- YAML blocks declare `type`, `source_field`, `target_entity`, `target_attribute`
- Transformation types use the vocabulary from the Transformations spec (Section 8)
- Destination column in source schema tables links correctly to transform anchors

#### Source-Domain Consistency

- Every canonical entity that is claimed to receive data from a source has at least one mapping (domain feed table entry or transform destination)
- Source fields that map to PII attributes are flagged if entity governance does not already declare `pii: true`
- No source references appear in entity detail files (source-agnostic canonical layer is maintained)

If no source systems are declared, skip this step but note the absence as advisory — most production domains should declare at least one source.

---

## Output Format for Reviews

Return findings grouped by severity with explicit remediation:

- **Critical**: structural breakages or compliance risks
- **Major**: high-impact modelling decision issues
- **Minor**: consistency, naming, or clarity improvements

Each finding must include:

- Artifact path
- Section heading
- What is wrong
- Why it matters (spec/decision impact)
- Concrete fix recommendation

Also include:

- **Pass Summary**: what is already correct
- **Decision Summary**: per requested dimension (granularity, temporal, existence, mutability, conceptual→logical, standards, regulations)
- **Readiness Verdict**: `Not Ready`, `Conditionally Ready`, or `Ready`

---

## Semantic Validation

Structural readiness is necessary but not sufficient. The review protocol above
validates what AI can check — spec conformance, internal consistency, declared
metadata. The following aspects require human domain expertise to validate and
**cannot be reliably assessed by AI alone**:

Aspect | Why AI Cannot Validate | Required SME
--- | --- | ---
**Entity completeness** | AI cannot know which real-world concepts are missing from the model — only which declared ones are malformed | Domain subject matter expert
**Relationship accuracy** | AI can verify cardinality syntax; it cannot verify that "Customer owns Account" is the correct business relationship (vs. "Customer holds Account") | Business analyst or domain owner
**Business process coverage** | AI cannot assess whether the modelled events and relationships capture the actual business workflow | Process owner or operations lead
**Governance correctness** | AI can verify governance YAML structure; it cannot verify that "7 years" is the correct retention period for a given jurisdiction | Legal or compliance counsel
**Standards alignment substance** | AI can verify a Reference column value exists; it cannot verify that the mapping is semantically correct for the organisation's use of that standard | Standards specialist
**Enum completeness** | AI can verify enum structure; it cannot know whether the listed values cover all real-world cases | Domain subject matter expert

When issuing a readiness verdict, mark semantic aspects as **Pending SME Review**
unless the user has explicitly confirmed them during the modelling session.

### SME Review Checklist

Include this in every review output:

```markdown
### Pending SME Review
- [ ] Entity completeness — are all real-world concepts represented?
- [ ] Relationship accuracy — do the modelled relationships match actual business rules?
- [ ] Business process coverage — do events capture the full lifecycle?
- [ ] Governance correctness — are retention periods, classifications, and PII flags verified?
- [ ] Standards alignment — are Reference column mappings substantively correct?
- [ ] Enum completeness — do enum values cover all real-world cases?
```

---

## Model Readiness Definition

A domain model's readiness verdict determines whether it can proceed to physical artifact generation (Agent Artifact) or data product design (Agent Architect).

### Ready

All of the following must be true:

- Zero Critical findings
- Zero Major findings
- All entities have `existence` and `mutability` declared
- All entities have at least one `identifier: true` attribute
- All relationships have `cardinality`, `granularity`, and `ownership`
- Domain metadata includes `classification`, `pii`, `regulatory_scope`, and `default_retention`
- Governance blocks on entities with PII or elevated classification are present
- Mermaid diagrams are syntactically valid
- No unresolved `# TODO:` markers in production-status domains

### Conditionally Ready

- Zero Critical findings
- One or more Major findings that do not affect the specific physical target requested
- Example: missing `mutability` on a reference entity that is not part of the requested schema scope

When issuing a Conditionally Ready verdict, list the specific conditions under which generation can proceed and which artifacts would be affected if the Major findings are not resolved.

### Not Ready

- One or more Critical findings, OR
- Major findings that would produce incorrect physical artifacts (wrong dimensional grain, missing identifiers, contradictory temporal strategy)

A Not Ready verdict must include a prioritised remediation plan.

### Handoff to Downstream Agents

When the verdict is **Ready**, tell the user which agents can now consume the model:

> "This domain is ready for physical artifact generation (Agent Artifact) and data product design (Agent Architect)."

When **Conditionally Ready**, specify the safe scope:

> "This domain can proceed to [specific artifact type] but [listed conditions] must be resolved before [other artifact type]."

---

## Review Guardrails

- Do not fabricate standards/regulatory facts.
- If uncertainty exists, mark as a question and request specific evidence.
- Prefer smallest corrective change that restores consistency.
- Keep structural findings and decision-quality findings distinct.
- When proposing fixes, preserve existing domain intent unless the user requests redesign.
- **Do not use error/reject language for convention or quality issues.** Use `flag` / `note` / `observe` / `suggest` for Levels 3–5 concerns. Reserve `error` language for syntax-level failures (Level 1) only.
- **Treat vocabulary deviations as observations.** If an organisation uses non-standard terminology, note it as "potential spec vocabulary gap" rather than "non-conformance". Include it in the Observations section of the review output, not in Critical or Major findings.