Data Model
When to use
- The work introduces or changes domain concepts: persistent entities, or the in-memory ones a stateless engine computes over (pricing, rules, workflow).
- Skip when domain concepts, relationships, transitions, and invariants are unchanged or already settled for this task. Existing concepts can still need remodeling; adding no new entity is not a skip.
Step 1: Model the domain
Open assets/data-model-section.md before the steps below fill it in.
- Fill the Concepts, Attributes, Relationships, and State transitions tables, following the template's note on each. Read an existing model's constraints, defaults, triggers, and indexes from its migrations or live schema, never from the code's model classes alone.
- For each invariant that must never break, name what enforces it (a constraint, a transaction boundary, a test, or a reconciliation) and who owns failures.
Step 2: Lenses, storage, evidence
- Apply each of the template's eight operational lenses that matches the risk. If a lens is omitted, write a skip record with that row's fields. Never drop one as "inapplicable" without it.
- If anything persists, note denormalized or cached data with its source of
truth, update boundary, and drift check. Fill the template's High-risk
classification block; a
pending classificationroute goes in Step 3's summary lines with the answer it waits on. For a change to an existing model on the ordinary route, define migration, mixed-version, and rollback behavior (changing-a-live-schemabuilds them). If any answer is off the ordinary route, record the domain constraints;migration-strategyowns the contract. - Trace representative reads, writes, transitions, concurrent operations, deletions, and existing-data migrations. When a runnable query exists, record it and its result. Otherwise name the check that will run later and who owns it; never pretend it ran. Where a new invariant, uniqueness rule, or required attribute lands on existing data, count the rows that break it today and record what happens to them.
Step 3: Write and present
Write the section to
.sdlc-skills/designs/{{YYYY-MM-DD}}-{{topic}}.mdor the user-set path and fill every field of the template's header; once its identity is issued, the section is never edited. Record that identity in its ledger (the decision record: add to it, never rewrite it, and keep it outside the design).Present:
{{Section}} {{path}} — version {{identity (per template)}} {{summary lines}} 1. Approve and hand off to planning 2. Request changes 3. Reject 4. Cancel Recommendation: {{option}} — {{one sentence}}.Ask this and end the turn;
clarifying-intentowns what closes it.If option 1 is chosen and every design section the work needs is approved, REQUIRED SUB-SKILL: invoke
writing-plansagainst this version. If a needed section is not approved yet, invoke its owning skill instead.
Gotchas
- The eight operational lenses in Step 2 are counted, and an omitted one needs its own skip record, but the lenses themselves live in the template, not in this file. Working from memory instead of the template's list is how a lens gets skipped with no skip record, because nothing here tells you which eighth lens you forgot.
- Cardinality has a steady-state value and a transitional one: during creation, before a required relationship holds, and during deletion, when a cascade fires into one. One recorded cardinality does not separate the two, so documenting only the steady state leaves the code free to do anything at those edges without that being a documented deviation.
Read references/worked-example.md when a full domain needs modeling end to
end at this level of rigor: null semantics, momentary versus lifetime
cardinality, state transitions, invariants, denormalization.