---
name: domain_modeling
description: Teach and run domain-driven design modeling before any code gets written: build a ubiquitous-language glossary, run an event-storming-lite board, carve out bounded contexts, and draw a context map. Use when starting a greenfield project or feature and the domain is fuzzy, when a team keeps arguing over what words mean, when a system has grown into a tangled model, or when planning where team and service boundaries should go.
---

# Domain Modeling

## Purpose

Model the domain before coding it. Most design arguments are really language arguments and boundary arguments. This skill runs the modeling discipline from Eric Evans' domain-driven design: capture the language the business actually speaks, storm the domain as a timeline of events, and split the result into bounded contexts with explicit relationships. The output is a set of documents a team or agent can design and build from.

## Workflow

### 1. Collect the domain story

Ask the user (or the domain expert) to narrate one typical day in the business, end to end, in plain words. No code, no databases, no API talk yet. Keep asking "and then what happens?" until the story covers the happy path and the two or three most common variations. Write it down verbatim first; interpretation comes later.

### 2. Build the ubiquitous-language glossary

Pull every business term out of the story into a glossary table: term, definition in the expert's own words, and where it shows up. Rules:

- One term, one meaning, inside one bounded context. If the same word means two things, that is a boundary signal, not a problem to argue away.
- Terms go into code later exactly as spelled here. If the name in the code drifts from the name in the glossary, one of them is wrong.
- When a term has synonyms, pick one and list the losers as aliases.

Use the template at `assets/glossary-template.md`.

### 3. Run event-storming lite

You do not need a wall or a workshop. Work the timeline solo or with the expert using the sticky grammar Alberto Brandolini defined:

- Orange: domain events, past tense ("Order Placed").
- Blue: commands, imperative ("Place Order").
- Light yellow: the actor issuing the command.
- Yellow: the aggregate that accepts the command and emits the event.
- Lilac: policies, phrased "whenever X, do Y".
- Green: read models the actor looked at before deciding.
- Pink: external systems outside your control.
- Red: hotspots, open questions, conflicts, places where the story got vague.

Walk the story left to right, event by event, and fill in the surrounding stickies with the causal loop: actor -> command -> aggregate -> domain event -> policy -> command. Every hotspot is an interview question for the next conversation. See `references/worked-example.md` for a full walkthrough.

### 4. Carve bounded contexts

Look at the board and find clusters of events and aggregates that change together for one reason. Each cluster is a candidate bounded context. Test each boundary:

- Does one ubiquitous language hold inside it? If two vocabularies live here, split.
- Would changing the model inside this cluster surprise anyone outside it? If yes, the boundary is real.
- Is the cluster about the core domain, a supporting subdomain, or a generic one? Spend the modeling effort on the core; buy or copy the generic parts.

Name each context in the business's words, not technical ones.

### 5. Draw the context map

For every pair of contexts that exchange information, name the relationship using Evans' patterns: Partnership, Shared Kernel (keep it small), Customer/Supplier, Conformist, Anti-Corruption Layer (an isolating layer that translates the upstream model into yours), Open Host Service, Published Language, Separate Ways. A Big Ball of Mud with no boundaries is a map too, and an honest one.

Mark which relationships cross team boundaries; those are the ones that need explicit agreements.

### 6. Sanity-check before design

- Every aggregate has at most one root that accepts its commands.
- Every domain event has exactly one aggregate that emitted it.
- Every hotspot has an owner and a follow-up question.
- Nothing in the model contradicts the glossary.

Only then is the model ready to inform code.

## Output Contract

A finished modeling pass produces, in this order:

1. **Domain story** — the verbatim narrative, one page.
2. **Glossary** — term, definition, aliases, using `assets/glossary-template.md`.
3. **Event board** — the timeline with commands, actors, aggregates, policies, read models, external systems, hotspots.
4. **Bounded contexts** — named clusters with their subdomain classification (core / supporting / generic).
5. **Context map** — named relationships between contexts.
6. **Hotspot list** — open questions, each with an owner and a next step.

## Operating Rules

1. Model before coding, every time. If someone asks to skip to the data model, finish the glossary first. The glossary is the cheapest artifact and the most valuable one.
2. The expert's words outrank the engineer's instincts. When they conflict, ask another question instead of modeling the guess.
3. Past tense for events, imperative for commands, "whenever X, do Y" for policies. Grammar sloppiness hides design sloppiness.
4. Hotspots are findings, not failures. A board with no hotspots was not examined hard enough.
5. Never present a context map you would not defend to the team that has to live with the boundaries.
6. This skill stops at the model. It does not generate code, schemas, or APIs; those belong to the implementation skills that consume these documents.