machenjie data-model-design
Registry Trigger
Use when
- design authoritative persisted records entities attributes relationships cardinality ownership lifecycle and enforceable invariants
Do not use when
- work is limited to repository mechanics, migration execution, transaction orchestration, consumer inventory, or DTO/model translation
Skill Role
Define the smallest authoritative logical or schema model that represents business facts and prevents material invalid states. Exclude repository behavior, migration execution, transaction protocols, and cross-layer mapping.
High-Value Rules
- Authority before shape. Record each changed fact's source of truth, mutation authority, lifecycle evidence, and uninspected writers.
- Complete semantics. State identity, cardinality, optionality, null/default meaning, lifecycle, history, and deletion behavior before selecting physical shape. Distinctions that change business behavior remain preserved.
- Owned enforcement. For each material invariant, choose the strongest boundary the current store and writer topology can honor. Name cross-record, cross-owner, or external-system races that remain.
- Evidence-driven shape. Choose normalization, embedding, derived state, and storage shape from named ownership, write, read, history, failure, and rebuild needs. Derived state names its authoritative source, lag tolerance, and reconciliation owner.
- Compatible evolution. State the conditions existing rows and mixed-version writers must satisfy. Hand data conversion, sequencing, rollback, and destructive rollout mechanics to
data-migration-design. - Bounded claims. Bound impact claims by inventorying affected schema, generated, job, report, and dynamic consumers; classify uninspected consumers and production distributions as unverified.
Anti-Patterns
- Reject transport, form, or report shapes promoted to authoritative models without ownership, lifecycle, and invariant evidence.
- Reject ambiguous lifecycle/null states, shared mutation without authority, and derived state without rebuild and reconciliation ownership.
- Reject constraints or destructive shape changes that current rows or mixed-version writers cannot satisfy.
- Reject no-consumer claims based only on a source search.
Stop Conditions
Stop when authority, identity, cardinality, or lifecycle evidence conflicts; regulated retention or deletion lacks an accountable owner; correctness depends on cross-owner atomicity; or unknown writers/consumers make compatibility unknowable. Source, fixture, and local validation evidence proves inspected paths, not production distribution, hidden writers, or external consumers.
Output Contract
- Return an authoritative data-model decision: define identity, relationships, ownership, lifecycle, invariants, enforcement, evolution constraints, evidence, and proof limits
Targeted References
| Path | Type | Load when | Do not load when | Required by | Required output |
|---|---|---|---|---|---|
| benchmarks and patterns | benchmark-pattern | Storage fit ownership normalization history or enforcement mechanisms compete | The root rules and current authority select one bounded model | task-agent, analysis-agent | option-comparison, selected-approach |
| checklist | decision-checklist | Model changes identity cardinality invariants lifecycle access deletion or mixed-version behavior | No authoritative entity relationship or storage contract changes | task-agent, analysis-agent | checklist-result, residual-risk |
| evidence patterns | evidence-pattern | Authority invariant consumer evolution or migration claims need fresh proof | Current schemas writers consumers and validators prove each bounded claim | task-agent, analysis-agent | evidence-record, proof-limit, residual-risk |