Domain Modeling

3. Relationship Mapping ⚡ (Power Mode)

Steps:

1. Identify relationships: has-one, has-many, belongs-to, many-to-many.
2. Draw a simple text-based ER diagram using Mermaid syntax.
3. Validate cardinality with the user.

Outputs

Edge Cases

• Ambiguous terms (e.g., "order" = purchase order or sort order) — Ask user to disambiguate. Record both meanings with context tags.
• Domain terms that conflict with language keywords — Prefix with domain abbreviation (e.g., OrderStatus not Status).

Scope

In Scope

• Extracting entities, attributes, and relationships from requirements artifacts.
• Creating and maintaining a domain glossary (glossary.md).
• Designating and enforcing Protected Terms that must never be renamed.
• Generating text-based ER diagrams (Mermaid syntax).
• Resolving ambiguous or overloaded domain terms with the user.

Out of Scope

• Gathering requirements (see requirements-elicitation).
• Designing database schemas or choosing storage engines (see database-design).
• Writing data-access code or ORM mappings (see data-access).
• Defining API contracts or resource naming (see api-contract-design).
• Runtime performance analysis of domain objects.

Guardrails

1. Protected Terms are immutable — Once a term is marked Protected, no skill may rename it without explicit user override logged in the audit trail.
2. Single source of truth — The glossary file is the canonical reference; do not define terms inline in other artifacts without a glossary entry.
3. No implementation details — Domain models describe what exists, not how it is stored or computed.
4. User-confirmed definitions only — Every entity and relationship must be validated by the user before being marked as confirmed.
5. Aliases must be recorded — If a term has synonyms in the domain, list all aliases in the glossary to prevent naming drift.
6. Mermaid diagrams stay current — Any change to entities or relationships must be reflected in the ER diagram within the same session.

Ask-When-Ambiguous

Pause and ask the user when:

• A noun could refer to more than one concept (e.g., "account" = user account or financial account).
• The cardinality of a relationship is unclear (one-to-many vs. many-to-many).
• An entity's boundary overlaps with another aggregate (composite vs. separate entity).
• A term already exists in the glossary with a different definition.
• The user introduces a new term that conflicts with a programming language keyword or framework convention.
• It is unclear whether a concept is an entity, a value object, or an enum.

Decision Criteria

Success Criteria

• All entities mentioned in requirements are captured in the glossary.
• Each entity has a clear definition, attributes list, and relationship mapping.
• Protected Terms are explicitly marked and acknowledged by the user.
• An ER diagram in Mermaid syntax accurately reflects all entities and relationships.
• No ambiguous or overloaded terms remain unresolved.
• The glossary is stored in the agreed location (glossary.md at project root).
• All aliases for each term are recorded.

Failure Modes

Audit Log

Every domain modeling session must produce an entry in the project's audit log:

| Timestamp | Skill | Action | Detail | Confirmed By |
|-----------|-------|--------|--------|--------------|
| <ISO8601> | domain-modeling | session-started | Domain modeling session begun | — |
| <ISO8601> | domain-modeling | entities-extracted | N entities identified from requirements | user |
| <ISO8601> | domain-modeling | glossary-created | glossary.md created with N terms | user |
| <ISO8601> | domain-modeling | protected-terms-set | N terms marked as Protected | user |
| <ISO8601> | domain-modeling | er-diagram-generated | Mermaid ER diagram produced with N entities | user |
| <ISO8601> | domain-modeling | glossary-updated | Term X added/modified | user |

Log entries are append-only. Corrections are recorded as new rows, never as overwrites.