Domain Model

ux-architecture designs what the screen shows when something is empty, loading or broken. This skill designs the things the product is about: what they are, what states they move through, who moves them, what must always be true, and how they are stored. A ticket reopened after it is closed, an invoice edited after it is sent: these are product decisions, and left to the build an agent makes them silently, one if at a time.

Mode. Standalone models the supplied domain and returns the entities, the rules and the prototype. In the lifecycle it runs in phase 4 after the flows and before the visual direction and the stack (the store depends on the shape of the data), writes DESIGN.md → ## Domain model, and gate 4.10 checks it. Both per operating modes. Read the domain method for the tables, the scenario technique, the logic prototype and a worked example.

Procedure

0. Start from what is settled. Read the project's DOMAIN.md, and the schema, migrations and status enums where repo.read resolved. On a product that exists, model the delta: the entities this work adds, the states and transitions it adds or changes, the invariants it touches. Every existing rule it changes is named as a change, with the initiative that set it, and asked as a round question. Where an invariant tightens, count the existing rows that already break it (db.query) and hand the number to the spec's Impact on what exists. Done when you can list what exists, what this work changes, and the rows affected.
1. Name the things. From the flows, the spec scope and PRODUCT.md: the entities the person acts on, each with a one-line definition in the product's words, checked against PRODUCT.md → Language. A term used two ways, or two terms for one thing, is a question for the person ("is a project the same as a workspace?"), settled first and written into Language. Done when every term has one meaning.
2. Give each entity its states and transitions. Per transition: who can trigger it, the guard (what must be true first), and the effect (notifications, other entities that change, what becomes irreversible). Draw each lifecycle under its table as a Mermaid stateDiagram-v2, one arrow per transition labeled with who, every state of the table in it (gate 4.20); the person reads the drawing when the rules are put to them. An entity with no lifecycle gets a line saying so. Done when every transition has who, guard and effect, and every lifecycle is drawn.
3. Write the invariants: the rules that hold whatever happens ("a ticket has exactly one assignee or none", "a paid invoice changes only by credit note"). Each is a candidate test and, where the store allows, a constraint. Done when every rule the flows imply is written as an invariant.
4. Stress it with scenarios. Walk concrete, awkward stories through the model: two people move the same ticket at once; the assignee leaves the team; a payment arrives for a cancelled order; the person undoes. Done when every scenario has an answer from the model or is listed as an undecided rule.
5. Put the rules to the person, in their words. Every undecided rule becomes a pressure-testing round question: options with what each means for the people using the product, a recommendation and why ("Can a closed ticket be reopened? A. Yes, by anyone… B. Only by its author… C. A new one is opened and linked…"). Hard-to-reverse ones (deletion, money, permissions) become ADRs. Done when every undecided rule has the person's answer.
6. Build a logic prototype when an entity has more than two states, a guarded transition, or a rule the person hesitated on: one HTML file at .builderos/initiatives/{initiative}/design/domain-prototype.html, a button per action, guided scenarios from step 4, the full state shown after every click, in the product's language. The logic sits in one pure, in-memory script module the build can lift. Done when the person has played it, before accepting the model.
7. Sketch the data. Per entity: the fields that matter, the relationships, and what is deleted with what. The shape, short of a migration: enough for system-design (stack) to choose a store and for the build to write the schema with every rule already decided. Done when each entity has fields, relationships and deletion behavior.
8. Record and explain. Write ## Domain model in DESIGN.md per the design template; at ship, phase 6 promotes it into DOMAIN.md (gate 6.9), and standalone work on a product with a DOMAIN.md proposes the edit there. Add a plain-language paragraph to the spec's ## What we chose: the main objects and the two or three rules that will surprise someone. New terms go into PRODUCT.md → Language. Done when gate 4.10 passes on the file.

Watch for

Capabilities

Output Contract

## DOMAIN MODELED with the entities, the transitions with who and guard, the invariants, the rules the person decided, the prototype path when built, and the data sketch.