Modeling Standard
Enforce model-first development — model IS source of truth, implementation follows
Tags
Overview
Purpose
Enforce model-first development — model IS source of truth, implementation follows
Rules
MDL-001: The model file IS the documentation. Implementation follows model, not vice versa.
When model and code diverge, the model is stale documentation. Making the model authoritative ensures one source of truth for all stakeholders.
Verification: Code review: verify implementation matches model structure. Any divergence must be reconciled — change model or change code.
MDL-002: All governance fields MUST have values. Empty fields indicate GAPS that block implementation.
Empty governance fields signal incomplete thinking. Starting implementation with gaps propagates ambiguity into code that's harder to fix later.
Verification: Schema validation: scan for empty required fields. Lint for placeholder values like 'TODO' or 'TBD'.
MDL-003: Every piece of implementation MUST trace back to a model definition.
Orphan code — implementation without a model origin — is ungoverned. It can't be validated against requirements and becomes technical debt.
Verification: Code review: for each new file or function, identify the model element it implements. No model element = no implementation.
MDL-004: Define purpose and goals BEFORE properties. Know WHY before WHAT.
Properties without purpose are arbitrary structure. Purpose-first modeling ensures every property serves a clear need and prevents speculative design.
Verification: Schema review: purpose and goals sections must be complete before properties section is populated.
MDL-005: Explicitly map to FDD layers (UI/SI/MD/PD). No implicit layer assignment.
FDD's 4-layer decomposition is the primary architectural structure. Implicit layer placement causes cross-layer coupling and unclear responsibilities.
Verification: Model review: every entity, component, and type must have explicit fdd_layer or x_spectral.fdd_layer assignment.
MDL-006: Run model validation BEFORE starting implementation. Block if incomplete.
Implementing against an incomplete model is building on sand. Validation catches gaps before they become expensive implementation errors.
Verification: Process gate: model validation must pass (all required fields populated, all traces resolved) before any implementation work begins.
MDL-007: Implementation differences from model MUST be reconciled — change model or change code.
Model-code drift erodes trust in both artifacts. Explicit reconciliation maintains the model-as-documentation contract.
Verification: Code review: any PR that diverges from model must include either a model update or an explanation why the model is wrong.