domain-design

Domain Design

Design from the behavior the business must observe and control. Source shape and implementation convenience are inputs, not the domain model.

Owns one invariant: an API, schema, or module boundary is derived from business questions and operations, then validated against them. It does not mandate DDD tactical patterns, ban CRUD, or replace architecture review or the ADR workflow. Quality principles (cohesion, coupling, YAGNI, minimal implementation) belong to the code-qualities-assessment skill; this skill applies them and does not restate them.

Triggers

design this schema, API design, where should this module boundary go, CRUD or domain operation, is this explicit state or reconstruction

When It Applies

A change adds or reshapes an API contract, a table or document schema, or a module boundary. A change that reuses an existing contract unchanged skips this skill.

Decision flow

business question or operation
  -> observable behavior + invariant
  -> state that must be explicit
  -> API/module contract, and schema/history model
  -> validate against use cases
  -> simpler adequate model? yes: adopt. no: revise boundaries and state.

Process

1. Discover the business question. Name the decisions, actions, and questions the system must support. Who observes or invokes each? Which outcomes, invariants, and time semantics matter? Write each question as a sentence a business owner would say.
2. Derive state. For each fact a question needs, decide: safe derivation or hidden reconstruction. A value computed cheaply from state you already hold is a derivation. A first-class fact rebuilt by joining or probing incidental rows (for example, "what have we fetched?" answered by scanning fact rows) is a reconstruction obligation. Row presence cannot tell a partial fetch from a complete one. Record that fact as explicit state. Mark which state changes over time and so needs history or effective-time.
3. Derive operations. Use a domain operation when the behavior carries invariants or multi-step transaction semantics that generic CRUD would leak (for example, "replace this site's reporting window"). Use CRUD when the entity is plain create, read, update, delete with no extra invariant. Do not invent domain verbs to avoid CRUD.
4. Derive the schema. Model domain state and invariants first. Treat an external or source payload as an integration contract that feeds the model, not as the model. Make important business facts queryable without rebuilding them from incidental traces.
5. Derive boundaries. Align module and API boundaries with behavior, invariants, ownership, and reasons to change. Reject a boundary that exists only because the payload, ORM, or transport format has that shape.
6. Validate against use cases. Walk three to five representative questions and commands through the design. Record any that need unrelated-table joins, inferred time, derived-state reconstruction, or coordination across boundaries. Treat repeated reconstruction or change amplification as design evidence, not query inconvenience. If a simpler adequate model exists, adopt it. Otherwise revise state or boundaries and walk again.