Skills/mcd-mld-designer/SKILL.md

name	description
mcd-mld-designer	Design, document, and maintain database Conceptual Models (MCD) and Logical Models (MLD) following strict Merise rules, naming conventions (<DB_TRIGRAM>_<TABLE> and <TBL_TRIGRAM>_<COLUMN>), and native Mermaid diagrams rendered in Antigravity and VS Code. Enforces tracking in db/mcd.md and db/mld.md, and must be used before any database modification.

MCD & MLD Database Designer

This skill guides the creation, update, and maintenance of relational database architectures using the Merise methodology (MCD to MLD) with graphical Mermaid.js diagrams that render natively inside Antigravity artifacts and Visual Studio Code Markdown viewers.

---

⚠️ Mandatory Pre-Modification Rule

[!IMPORTANT] No database change may be made without this skill. Before creating tables, adding columns, modifying relationships, writing ORM models, or running database migrations:

1. Read and inspect existing schemas in db/mcd.md and db/mld.md.
2. Apply all conceptual (MCD) and logical (MLD) modifications according to this skill.
3. Update and persist changes directly in db/mcd.md and db/mld.md.
4. Ensure AGENT.md (or GEMINI.md) in the project enforces this rule (see AGENT.md Rule Template).

---

1. Strict Naming Conventions

All identifiers and data types must be in UPPERCASE.

1.1 Database Trigram (<DB_TRIGRAM>)

• Derived from the database or project name: first 3 alphanumeric characters, uppercase, stripped of accents/special characters (or an explicit 3-letter trigram requested by the user).
• Examples:
  • Database ECOMMERCE ➔ ECO
  • Database INVENTORY ➔ INV
  • Database HEALTHCARE ➔ HEA

1.2 Table Names (<DB_TRIGRAM>_<NAME_OF_TABLE>)

• Every table is prefixed with <DB_TRIGRAM>_ followed by the functional entity name in UPPERCASE.
• Examples:
  • ECO_CUSTOMER
  • ECO_ORDER
  • ECO_PRODUCT

1.3 Table Trigram (<TBL_TRIGRAM>)

• Derived from the functional table name (without the DB prefix): first 3 characters of the table name.
• Examples:
  • CUSTOMER ➔ CUS
  • ORDER ➔ ORD
  • PRODUCT ➔ PRO
  • CATEGORY ➔ CAT

1.4 Column Names (<TBL_TRIGRAM>_<NAME_OF_COLUMN>)

• Every column is prefixed with its table's 3-letter abbreviation.
• Examples for ECO_CUSTOMER (CUS):
  • CUS_ID (Primary Key)
  • CUS_FIRST_NAME
  • CUS_LAST_NAME
  • CUS_EMAIL
  • CUS_CREATED_AT

1.5 Foreign Keys (<HOST_TBL_TRIGRAM>_<TARGET_TBL_TRIGRAM>_<COLUMN_NAME>)

• When Table A references Table B, the foreign key column in Table A is prefixed with HOST_TBL_TRIGRAM_TARGET_TBL_TRIGRAM_:
• Examples:
  • Table ECO_ORDER (ORD) referencing ECO_CUSTOMER (CUS): ➔ Foreign Key column: ORD_CUS_ID
  • Table ECO_PRODUCT (PRO) referencing ECO_CATEGORY (CAT): ➔ Foreign Key column: PRO_CAT_ID

1.6 Associative / Junction Tables (N:M Relationships)

• Use meaningful functional names whenever applicable (e.g. ECO_ORDER_ITEM), or concatenation of entities (e.g. ECO_ORDER_PRODUCT).
• Table trigram follows the functional name:
  • ECO_ORDER_ITEM ➔ Trigram ITE
  • Columns: ITE_ORD_ID (FK referencing ECO_ORDER), ITE_PRO_ID (FK referencing ECO_PRODUCT), ITE_QUANTITY, ITE_UNIT_PRICE.
  • Primary Key is composite: (ITE_ORD_ID, ITE_PRO_ID).

---

2. File-Based Tracking Architecture

All database artifacts must be stored and maintained under the project's db/ folder:

<project_root>/
├── db/
│   ├── mcd.md       # Conceptual Data Model (Data Dictionary + Mermaid Flowchart MCD)
│   └── mld.md       # Logical Data Model (Relational schema text + Mermaid erDiagram MLD)
├── AGENT.md         # Contains the mandatory rule requiring this skill before DB edits

Protocol for Any Database Edit:

1. Never edit code or SQL migrations directly without first updating db/mcd.md and db/mld.md.
2. Review db/mcd.md: Update the Data Dictionary, add/modify entities, associations, and cardinalities in the MCD Mermaid flowchart.
3. Review db/mld.md: Translate MCD updates into relational tables, foreign keys, constraints, and update the MLD Mermaid erDiagram.
4. Synchronize & Document: Add a changelog entry at the bottom of both db/mcd.md and db/mld.md detailing the version, date, and changes made.

---

3. End-to-End Modeling Workflow

Follow this 4-step sequence whenever modeling or extending a database:

Step 1: Requirements & Data Dictionary

Extract all entities and properties from user requirements or business domain. Construct the Data Dictionary table:

Code Propriété	Libellé / Description	Type	Contraintes	Entité Source
CUS_ID	Identifiant client	INT	PK, AUTO_INCREMENT	CUSTOMER
CUS_EMAIL	Adresse e-mail	VARCHAR(150)	UNIQUE, NOT NULL	CUSTOMER
ORD_ID	Numéro de commande	INT	PK, AUTO_INCREMENT	ORDER

(In English contexts, use English column headers: Property Code, Description, Type, Constraints, Source Entity)

Step 2: Conceptual Data Model (MCD)

• Identify Entities (Entités) and Associations (Relations).
• Define Merise Cardinalities:
  • 0,1: Optional single link (zero or one)
  • 1,1: Mandatory single link (exactly one)
  • 0,N: Optional multiple link (zero to many)
  • 1,N: Mandatory multiple link (at least one)
• Render the MCD using a Mermaid Flowchart (flowchart LR or flowchart TD) compatible with Antigravity and VS Code:
  • Entities as rectangular nodes with attributes.
  • Associations as rounded/oval nodes ((Association)).
  • Links annotated with cardinalities: ENTITE_A ---|"1,N"| ASSOC ---|"1,1"| ENTITE_B.
• Save in db/mcd.md.

Step 3: Logical Data Model (MLD)

Apply the standard Merise transformation rules (see Merise Rules Reference):

1. One-to-Many (1,N - 1,1 or 0,1):
   • The primary key of the (0,N) or (1,N) entity migrates into the (1,1) or (0,1) entity as a foreign key.
   • Named: <HOST_TRIGRAM>_<TARGET_TRIGRAM>_<COL> (e.g. ORD_CUS_ID).
2. Many-to-Many (0,N/1,N - 0,N/1,N):
   • The association becomes a junction table <DB_TRIGRAM>_<NAME>.
   • Its primary key is composite, formed by foreign keys to both participating entities.
   • Any attributes of the association become columns in this junction table.
3. Write Relational Schema Text:
   • Primary Keys are underlined (or indicated with (PK)).
   • Foreign Keys are marked with # (or (FK)).
   • Example:

     ECO_CUSTOMER (CUS_ID, CUS_FIRST_NAME, CUS_LAST_NAME, CUS_EMAIL)
     ECO_ORDER (ORD_ID, ORD_DATE, ORD_TOTAL_AMOUNT, #ORD_CUS_ID)
     ECO_ORDER_ITEM (#ITE_ORD_ID, #ITE_PRO_ID, ITE_QUANTITY, ITE_UNIT_PRICE)
     

4. Render Mermaid erDiagram:
   • Use standard Mermaid ER syntax with exact table names and typed columns.
   • Save in db/mld.md.

Step 4: Normalization Verification (3NF)

Verify all schemas comply with the 3 Normal Forms:

• 1NF: All attributes are atomic (no repeating groups or comma-separated lists).
• 2NF: In 1NF and all non-key attributes are fully functionally dependent on the entire primary key (no partial dependency on part of a composite key).
• 3NF: In 2NF and no transitive functional dependencies (no non-key attribute depends on another non-key attribute).

---

4. Bilingual Support (French / English)

Adapt the vocabulary and documentation language automatically to the language used by the user:

• French: Modèle Conceptuel de Données (MCD), Modèle Logique de Données (MLD), Entités, Associations, Cardinalités, Dictionnaire des Données, Clé Primaire (PK), Clé Étrangère (FK).
• English: Conceptual Data Model (CDM / MCD), Logical Data Model (LDM / MLD), Entities, Relationships, Cardinalities, Data Dictionary, Primary Key (PK), Foreign Key (FK).

The strict naming conventions (<DB>_<TABLE> and <TBL>_<COLUMN>) and Mermaid diagram syntax remain strictly enforced regardless of language.

---

5. References & Examples

• AGENT.md Rule Template: Setup instructions to enforce this skill in AGENT.md / GEMINI.md.
• Merise Transformation Rules: Detailed formal rules for translating MCD associations to MLD relations.
• Mermaid Diagram Syntax: Formatting rules and templates for Antigravity & VS Code compatibility.
• Complete E-Commerce Example: Fully worked example with db/mcd.md and db/mld.md templates.