| name | domain-modeling |
| description | MANDATORY modeling protocol. You MUST invoke this skill when designing a data model, domain model, database schema, or the core entities and relationships of a system — "design the schema", "model this domain", "what tables/entities do we need". Do NOT jump to tables or classes before the invariants are named. Do NOT leave illegal states representable. Invoke BEFORE writing migrations, ORM models, or type definitions for the domain. Does NOT apply to choosing a database engine (use architecture-reasoning).
|
Domain Modeling Protocol
EXTREMELY_IMPORTANT: This is a MANDATORY protocol, not a suggestion. Follow every step.
Do not skip steps. Do not combine steps. Do not summarize. Work through each gate in order.
A schema that permits a state the business forbids is a bug you will spend months patching in
application code. The model's job is to make illegal states impossible, not merely unlikely.
Name the rules before you name the columns.
STEP 1 — Name entities in the domain's own language
List the core entities using the words a domain expert would use (ubiquitous language). If
you are inventing names no one in the business would recognize, you are modeling your first
guess at the solution, not the domain — go back to the domain's vocabulary.
STEP 2 — State each entity's invariant
For EVERY entity, write at least one rule that must ALWAYS be true ("an order's total equals
the sum of its line items"; "a lent copy has exactly one borrower"). An entity with no
invariant is a bag of fields — question whether it is really an entity or just attributes of
another one.
STEP 3 — Assign lifecycle ownership across relationships
For every relationship, name which side OWNS the lifecycle (creates/deletes the other) and
which merely references it. Unowned or doubly-owned relationships are where orphan rows and
cascade-delete surprises come from. State the cardinality too (1:1, 1:N, N:M).
STEP 4 — Make illegal states unrepresentable
List the states the domain FORBIDS ("a copy lent to two members at once", "a hold on a copy
that is available"). For each, check the current model: does it still allow that state? If
yes, change the model — a required field, a unique constraint, a type, a moved relationship —
so the state cannot be expressed. If it truly cannot be prevented structurally, flag it as
requiring a runtime guard and say why.
STEP 5 — Report
DOMAIN MODEL: [system]
├── Entities: [entity → its invariant(s), one line each]
├── Relationships: [A—B, cardinality, which side owns lifecycle]
├── Illegal states forbidden: [state → made-unrepresentable how, or runtime-guarded + why]
└── Confidence: [HIGH / MEDIUM / LOW]
Confidence: HIGH — every entity has an invariant, ownership is unambiguous, forbidden
states are structurally prevented. MEDIUM — some rules rely on runtime guards. LOW —
core invariants are still unclear or ownership is contested; resolve before migrating.
Do NOT present the model until:
- Every entity has at least one stated invariant
- Every relationship names its owning side and cardinality
- Each domain-forbidden state is either made unrepresentable in the model, or explicitly
flagged as only runtime-guarded with a reason
A schema presented as a list of tables and columns with no invariants and no forbidden-state
check is a protocol violation, even if it "looks complete".
Red flags that this skill catches:
- "I'll just add the obvious fields" — fields without invariants encode no rules; the illegal
states leak into every query. State the rule first.
- "Ownership is obvious from the foreign key" — a foreign key says 'references', not 'owns'.
Name who deletes whom.
- "We can validate that in the app layer" — sometimes true, but decide it deliberately per
forbidden state, not as the default that lets the schema permit nonsense.
- "It's a simple domain" — simple domains still forbid states. Name three and check them.
Handoff
Once the model holds, hand it to implementation for migrations/types, and to
architecture-reasoning if the model reveals a boundary or storage decision worth weighing.
