patterns-entity-modeling

# Modeling Domain Entities

## Overview

Extract and model domain entities from requirements using Domain-Driven Design principles. This skill covers entity identification, attribute definition, relationship modeling, and state machine documentation.

## When to Use

- Creating data-model.md from requirements or specifications
- Extracting entities from user stories and functional requirements
- Defining attributes, types, and constraints for entities
- Modeling relationships between entities with cardinality
- Documenting state machines for stateful entities
- Brownfield analysis of existing data models

## When NOT to Use

- **API contract design** - Use `humaninloop:patterns-api-contracts` instead
- **Database schema migration** - This skill is conceptual, not implementation
- **When data model already exists and is complete** - Don't duplicate work
- **Pure validation rules** - Model entities first, then add validation
- **Technical architecture decisions** - Use `humaninloop:patterns-technical-decisions`

## Entity Extraction

### Identification Heuristics

Look for entities in:

| Source | Pattern | Example |
|--------|---------|---------|
| **User stories** | "As a [Role]..." | User, Admin, Guest |
| **Subjects** | "The [Entity] must..." | Task, Order, Product |
| **Actions** | "...create a [Entity]" | Comment, Message, Report |
| **Possessives** | "[Entity]'s [attribute]" | User's profile, Order's items |
| **Status mentions** | "[Entity] status" | TaskStatus, OrderState |

### Entity vs. Attribute Decision

```
IF concept has its own lifecycle → Entity
IF concept only exists within another → Attribute
IF concept connects two entities → Relationship (possibly join entity)
IF concept has just one value → Attribute

Examples:
- "user email" → Attribute of User (just one value)
- "user address" → Could be Entity (if reused) or Attribute (if embedded)
- "order items" → Separate entity (has own lifecycle)
- "task status" → Enum/attribute (limited values)
```

###