---
name: entity-modelling
description: Use this skill when modelling entities or their attributes, when the user says "types of" or "kinds of" something, when inheritance questions arise, or when deciding whether a concept should be a first-class entity, an enum, an attribute, or a relationship attribute. Also use when the user is unsure whether two similar concepts are the same entity or separate ones.
---

# Skill: Entity Modelling

Covers concept realisation decisions, inheritance hierarchies, entity YAML structure, attribute definitions, constraints, and enumeration definitions.

## MD-DDL Reference

- Full entity specification: `md-ddl-specification/3-Entities.md`
  (reference stub: `references/entities-spec.md`)
- Full enumeration specification: `md-ddl-specification/4-Enumerations.md`
  (reference stub: `references/enumerations-spec.md`)
- Conceptual-to-physical realization guidance: `conceptual-to-physical-realisation.md`
  (use for ownership/cardinality decisions, dimensional implementation reasoning, and final `existence` value selection)
- Entity-vs-enum classification deep guidance: `guidance.md`
  (use when concept boundaries are ambiguous or multiple structures are plausible)
- Inheritance pattern deep guidance: `inheritance-patterns.md`
  (use when evaluating subtype hierarchies, abstract parents, and discriminator alternatives)
- Physical realization guidance: defer to **Agent Artifact**
  (when user asks for dimensional/star-schema design, SQL DDL, 3NF outputs, or non-dimensional physical artifacts)
- Cross-skill standards guidance: `../standards-alignment/SKILL.md`
  (load before locking entity structure in industry-standard domains)

Read the relevant reference before drafting any entity or enum. Key sections:

**Entities spec:** Entity Declaration, Entity Diagram rules, Entity Definition (YAML),
Key-as-Name principle, Attribute Properties, Type System, Constraint Definition, Temporal Tracking, Existence, Mutability, Naming Rules.

**Enumerations spec:** Enum Declaration, Simple vs. Dictionary format,
Naming Rules (natural language values).

If modelling in a recognized industry domain (banking, payments, insurance,
healthcare, telecom), load `../standards-alignment/SKILL.md` before finalizing:
- entity boundary (entity vs enum vs relationship attribute)
- `existence`
- `mutability`
- temporal tracking strategy

---

## Concept Realisation Framework

When the user is uncertain what a concept *is*, apply this framework and explain your reasoning before drafting anything.

### Make it an Entity if:
- It has its own identity and lifecycle independent of other entities
- It will have relationships to multiple other entities
- It will accumulate attributes over time
- It is auditable or requires its own governance posture
- It can exist before or after the things it relates to

### Make it an Enum if:
- It is a fixed or slowly-changing controlled vocabulary
- It classifies or categorises another entity
- It has no attributes beyond a label and optional metadata (description, sort order)
- No one will ever say "tell me everything about this [value]"

### Make it a Relationship Attribute if:
- The property only makes sense when two specific entities are connected
- It describes the terms or nature of a connection, not a standalone fact
- Examples: `effective_date` on a role assignment; `limit` on a credit facility link

### Make it an Attribute of an existing Entity if:
- It is a simple property with no independent lifecycle
- It is only ever referenced through its parent entity
- It cannot be shared across or re-used by other entities

**When it is genuinely ambiguous**, present the options to the user as a short trade-off table:

Option | Advantage | Disadvantage
--- | --- | ---
Separate entity | Full governance, auditable, extensible | More relationships to manage
Attribute | Simpler model | No independent lifecycle or audit trail
Enum | Zero maintenance if stable | Can't evolve to carry attributes later without a refactor

---

## Inheritance Reasoning

When a user describes "types of" something, or entities that share common properties, walk through this logic explicitly before committing to a hierarchy.

**Step 1 — Is shared behaviour real?**
Do the candidate subtypes share actual attributes and constraints, or just a label?
If only a label → use an Enum discriminator on a single entity, not inheritance.

**Step 2 — Is the parent instantiated directly?**
Will anyone ever create a bare instance of the parent, or only ever a specific subtype?
If only subtypes → mark the parent `<<abstract>>` in the classDiagram.

**Step 3 — Do subtypes add meaningful attributes or constraints?**
If the subtypes are identical except for a type label → discriminator attribute is cleaner.
If subtypes add 3+ distinct attributes or meaningfully different constraints → separate entities with inheritance.

**Step 4 — Will subtypes diverge over time?**
High divergence expected → separate entities now, even if they look similar today.
Stable and similar → discriminator attribute with an enum.

Present this reasoning to the user before drafting. Do not silently choose a pattern.

---

## Existence and Mutability

Before finalizing these in an industry-standard domain, confirm Standards Alignment
has been loaded so the decision reflects standard semantics (for example, BIAN role
abstractions, ISO payment concepts, or FHIR resource boundaries).

These should be defined for every entity. They directly drive physical artifact generation — do not omit them or leave them as defaults without a conscious decision that the user will never want to generate schemas.

**Existence** (what is this entity's independence?)

Value | Use when | Generation hint
--- | --- | ---
`independent` | Meaningful on its own | Candidate dimension
`dependent` | Only meaningful in context of other entities | Candidate fact
`associative` | Resolves a many-to-many; carries relationship attributes | Bridge table

**Mutability** (how does this entity's data change?)

Value | Use when | Generation hint
--- | --- | ---
`immutable` | Once written, never changes | Ledger / event store
`append_only` | New rows added; existing rows never updated | Log / transaction
`slowly_changing` | Changes occasionally; history may matter | SCD Type 2
`frequently_changing` | Changes often; current value is what matters | Overwrite
`reference` | Essentially static; admin-managed | Small lookup table

Ask the user explicitly if these are not obvious. A wrong existence value produces a wrong dimensional model.

When relationship cardinality/ownership materially affects dimensional realization, apply `conceptual-to-physical-realisation.md` before finalizing `existence`.

---

## User Story to Modelling Signals

When user stories are available (from a BA, product owner, or requirements doc),
parse each story before deciding existence, mutability, and temporal tracking.
User stories encode the *why* behind these decisions; deriving them from
structural abstractions alone misses the business intent.

### Story Pattern → Modelling Decision

Story pattern | Existence signal | Mutability signal | Other signal
--- | --- | --- | ---
"…see all [X]s for a [Y] over time" | X is `dependent` on Y | X is `append_only` or `immutable` | Temporal tracking likely needed on X
"…reconstruct what [X] looked like at [date]" | — | `append_only` or bi-temporal | Temporal tracking required; flag for compliance review
"…query [X] with [Y] and [Z] context in real time" | X is likely `dependent` | X is `append_only` or `immutable` | Consumer-aligned product; SLA required; relationship granularity between X–Y and X–Z matters
"…analyse trends in [X] over [period]" | X is `independent` or `dependent` | `append_only` | Analytical product; wide-column or dimensional schema type
"…manage [X]" (CRUD operations) | X is `independent` | `frequently_changing` or `slowly_changing` | Operational product; normalized schema type
"…look up [X] by [identifier]" | X is `independent` | `reference` or `slowly_changing` | Lookup / reference data pattern
"…flag [X] when [condition]" | — | — | Constraint or event on X; consider an event rather than a polling pattern
"…see current [X] for [Y]" | X is `dependent` | `frequently_changing` | Current-state product; no temporal tracking needed
"…audit who changed [X] and when" | — | — | `audit` stereotype on X; governance `compliance_relevance` field

### How to Apply

1. Before deciding existence and mutability, collect all user stories that mention
   the entity.
2. Apply the table to each story. If stories conflict (e.g., one needs current state,
   another needs history), surface the tension to the user explicitly — it often
   signals two separate data products from one canonical entity.
3. Where a story implies a product access pattern, note it for Agent Architect:
   the entity's existence and mutability decisions should align with the product
   class and schema type the story implies.

> "I see two user stories that conflict: one needs current state of [X], the other
> needs full history. The canonical entity can support both — `append_only` mutability
> with a current-state view in one product and a history view in another. Shall I
> model it that way?"

---

## Governance Authoring Protocol

Apply governance metadata to every entity during drafting — do not defer governance to a later pass. The spec defines the authoritative schema in `3-Entities.md § Governance Metadata Schema`.

### Domain-Level Governance (set once in domain.md)

Every domain file must declare these four fields in its metadata YAML:

Field | Purpose
--- | ---
`classification` | Data sensitivity tier (`Public`, `Internal`, `Confidential`, `Highly Confidential`)
`pii` | Whether the domain handles personal data by default
`regulatory_scope` | Applicable regulations and frameworks (list)
`default_retention` | Base retention period for entities that do not override

Set these during domain scoping (see `../domain-scoping/SKILL.md`). They become the inherited defaults for all entities in the domain.

### Entity-Level Governance (override only what differs)

Entity governance blocks are optional overrides. Include a `governance:` YAML block on an entity only when it needs to differ from or extend the domain defaults.

**Override fields** (replace the domain default for this entity):
- `pii`, `classification`, `retention`, `access_role`

**Extension fields** (add entity-specific detail, no domain default exists):
- `retention_basis`, `compliance_relevance`, `regulatory_reporting`, `description`

When drafting an entity:

1. **Check domain defaults** — if the entity's governance posture matches the domain, add only `retention_basis` explaining why it inherits the default.
2. **Override where needed** — if `pii`, `classification`, `retention`, or `access_role` differ from the domain, include those fields.
3. **Add compliance detail for regulated entities** — entities directly involved in regulatory reporting should include `compliance_relevance` and `regulatory_reporting` listing specific obligations.
4. **Mark uncertainty** — if you cannot determine governance posture, add `# TODO: Confirm classification with data steward` rather than guessing.

### Handoff to Regulation Agent

Entity-modelling sets first-pass governance during authoring. Agent Governance audits and maintains that metadata over time. Do not attempt to resolve jurisdiction-specific compliance questions — flag them and defer to Agent Governance.

---

## Entity Detail File Checklist

Before presenting a drafted entity detail file:

- [ ] File begins with H1 heading with domain name as a link to domain.md
- [ ] Entity introduced with H3 heading under `## Entities`
- [ ] classDiagram present immediately after description, before YAML
- [ ] ELK layout engine declared in diagram config
- [ ] Subject class shows all attributes with correct Mermaid type syntax
- [ ] Inherited attributes are **not** repeated in the subject class
- [ ] Primary identifier prefixed with `*` in diagram
- [ ] Abstract entities marked `<<abstract>>`
- [ ] All reference classes defined at bottom of diagram with hyperlinks
- [ ] At least one attribute with `identifier: true` in YAML
- [ ] `existence` and `mutability` declared
- [ ] No foreign key attributes present
- [ ] Domain-level governance defaults are confirmed for the entity
- [ ] If a `governance:` block is present, it contains only override fields and `# TODO:` where required
- [ ] Constraint keys use natural language (Key-as-Name principle)

---

## Enum Detail File Checklist

- [ ] File begins with domain H1 heading and link back to domain.md
- [ ] Enum under H3 heading within `## Enums` section
- [ ] Values use natural language (not PT, ACTIVE, HI_CONF)
- [ ] Dictionary format used if values carry metadata (description, sort order, score)
- [ ] Simple list format used if values are labels only