ddd ยท diff
git:20260921.3066ef1 to git:20260921.1d9903e
108 added, 105 removed. Audit A to A.
---
name: ddd
description: >-
- Design, implement, review, or refactor domain models through collaboration
- with the user as the domain expert. Use for domain-driven design, domain
- modeling, ubiquitous language, entities, value objects, domain services,
- aggregates, factories, repositories, domain events, or code whose business
- concepts and rules need to be made explicit. Inspect existing systems before
- interviewing, propose a model for confirmation, then implement only after the
- user approves it. Remain language- and programming-paradigm agnostic.
+ Write, revise, or consolidate DOMAIN.md, a repository's domain model, by
+ interviewing the user as the domain expert. Use to create DOMAIN.md, to model
+ a domain with domain-driven design (ubiquitous language, entities, value
+ objects, domain services, aggregates, domain events, rules and invariants),
+ when a task introduces a term, rule, or concept absent from DOMAIN.md, when
+ code and DOMAIN.md disagree, or to remove inconsistencies and redundancies
+ from an existing DOMAIN.md. Produces the document only; it does not implement
+ or refactor code.
---
# Domain-Driven Design
- Build software around a shared, explicit model of the domain. Treat the user as
- the domain expert: extract rules through concrete scenarios, reflect them in a
- proposed model, and require confirmation before implementation or refactoring.
+ Agents already know domain-driven design. What they lack is the domain: the
+ terms, rules, and boundaries of this business. `DOMAIN.md` supplies that. It
+ records the ubiquitous language, the model, and the rules and invariants, so
+ every later task starts from the same model instead of re-deriving one from
+ code.
- Read [`references/domain-driven-design.md`](references/domain-driven-design.md)
- before modeling. Use it as the source of truth for concepts and review criteria.
+ This skill writes and maintains `DOMAIN.md` at the repository root. Treat the
+ user as the domain expert: extract rules through concrete scenarios and write
+ down only what they confirm. The skill does not change code. Bringing the
+ implementation in line with the model is separate work that reads `DOMAIN.md`.
+ [`references/domain-driven-design.md`](references/domain-driven-design.md) is
+ this skill's definition of domain-driven design. Read it:
+
+ - before the first interview in a repository, for the interview technique and
+ the modeling concepts
+ - when mapping evidence from an existing system to concepts; its "Bring Key
+ Concepts Into Light" and "Review an Existing System" sections say what to
+ look for
+ - during a consolidation pass, for what makes a term or boundary precise
+
+ The reference says to keep the model and the implementation aligned. That
+ alignment is the goal; a lag is the expected state. This skill keeps the model
+ explicit and current, and closing the gap is code work outside it.
+
## Operating Contract
- Never invent domain rules. Ask the user when behavior, terminology,
invariants, or exceptions are unclear.
- - Allow an assumption only when the user explicitly approves it. Record approved
- assumptions in the model proposal and preserve them through implementation.
- - Do not edit implementation files until the user confirms the proposed model.
+ - Write only confirmed content. An assumption the user approves is a rule;
+ write it as one. Open questions stay in the conversation, never in
+ `DOMAIN.md`.
+ - `DOMAIN.md` describes the goal state: how the software is supposed to work.
+ The implementation may lag it. Never rewrite the document to match the code
+ without asking. When code and document disagree, ask whether the model was
+ incomplete or the code drifted.
+ - Edit `DOMAIN.md` only. Do not edit implementation files, tests, or schemas.
- Prefer entities, value objects, domain services, aggregates, factories,
repositories, and domain events when they clarify the model. Do not force a
pattern without a concrete domain responsibility.
- Do not require classes, inheritance, mutable objects, or object-oriented
- programming. Express the model using mechanisms natural to the project.
+ programming. The model is independent of programming paradigm.
- Do not introduce or recommend bounded contexts. Keep this skill focused on
domain knowledge, explicit models, consistency boundaries, and evolution.
- - Keep the ubiquitous language consistent across conversation, implementation,
- tests, interfaces, and durable documentation.
## Workflow
### 1. Establish The Evidence
- For an existing system, inspect the relevant code, tests, schemas, interfaces,
- documentation, and recent changes before interviewing the user. Identify:
+ Read `DOMAIN.md` first when it exists. For an existing system, also inspect the
+ relevant code, tests, schemas, interfaces, documentation, and recent changes
+ before interviewing the user. This step is read-only. Identify:
- current domain terms and competing synonyms
- behavior and rules embedded in conditionals or orchestration
- identities, values, state transitions, and consistency boundaries
- duplicated or scattered domain logic
- - persistence concerns leaking into domain behavior
- - differences between documentation, tests, and implementation
+ - concepts present in the code but absent from `DOMAIN.md`, and the reverse
- For a new system, begin with the user's stated problem, actors, desired outcomes,
- and representative scenarios. Do not design from nouns or storage structures
- alone.
+ Evidence produces questions, not rules. Code shows what is implemented, not
+ what is intended.
+ For a new system, begin with the user's stated problem, actors, desired
+ outcomes, and representative scenarios. Do not design from nouns or storage
+ structures alone.
+
Do not stop after announcing that inspection or an interview is needed. Inspect
available artifacts in the current turn. If no relevant artifacts are available,
start the domain interview immediately.
### 2. Interview The Domain Expert
Use the available interactive question tool. If none is available, ask concise
questions in prose. Ask no more than three or four questions per round and run
additional rounds until material ambiguity is resolved.
Ground questions in concrete cases:
1. Ask what happens in a representative scenario from beginning to end.
2. Clarify the terms the user uses for actors, concepts, actions, and outcomes.
3. Ask what must always be true before and after meaningful operations.
4. Probe exceptions, rejected actions, state transitions, and competing cases.
5. Test the emerging model with counterexamples and boundary cases.
Do not ask the user to choose technical patterns. Ask domain questions, then map
the answers to modeling tools. When an answer exposes a contradiction or a term
with multiple meanings, continue the interview instead of resolving it silently.
- ### 3. Propose The Model
-
- Present a concise model for confirmation before editing code. Include only
- sections relevant to the task:
-
- ```markdown
- ## Ubiquitous language
- - **Term**: precise domain meaning
-
- ## Model
- - **Entity**: identity, lifecycle, behavior
- - **Value object**: meaning, attributes, constraints
- - **Domain service**: operation and why it belongs outside one concept
- - **Aggregate**: root, boundary, invariants, consistency requirements
- - **Factory**: creation rules that require encapsulation
- - **Repository**: domain-oriented retrieval and persistence needs
- - **Domain event**: meaningful occurrence, payload, consumers
-
- ## Rules and invariants
- - Rule expressed in domain language
-
- ## Existing-system mapping
- - Current construct -> proposed concept or change
+ ### 3. Write DOMAIN.md
- ## Approved assumptions
- - Assumption explicitly approved by the user
- ```
+ The file is the proposal. Draft or edit `DOMAIN.md`, then have the user review
+ the change and correct it. Iterate until they confirm. Revise an existing file
+ in place: change the affected terms and rules where they live instead of
+ appending a new section or a changelog.
- Explain why each selected pattern fits. Omit unused patterns instead of filling
- the proposal with placeholders. Lean strongly toward explicit modeling tools
- when business meaning would otherwise remain in primitives, flags, generic
- services, infrastructure code, or unwritten convention.
+ Open the document with a short statement of what it is: the source of truth for
+ the ubiquitous language, domain rules, and how the software is supposed to work;
+ a living goal-state document that implementation may lag.
- Ask the user to confirm or correct the proposal. Do not proceed on silence or
- partial agreement when unresolved points would change behavior or boundaries.
+ A useful outline, to adapt rather than fill in:
- ### 4. Implement Or Refactor
+ 1. **Ubiquitous language**: each term and its precise meaning
+ 2. **Model**: entities and aggregates, domain services, domain events
+ 3. **Rules and invariants**: what must always hold, grouped by topic
+ 4. **Lifecycles and processes**: states, transitions, and sequences
- After confirmation, map the approved model onto the project's existing language,
- architecture, and conventions.
+ Include only what the domain needs. Omit a section or pattern that has no
+ concrete domain responsibility instead of adding placeholders.
- - Make domain terms visible in names and public operations.
- - Keep invariants close to the operations and boundaries that enforce them.
- - Represent meaningful values explicitly rather than passing unrelated
- primitives when the language permits a clearer representation.
- - Keep domain behavior separate from transport, storage, framework, and UI
- concerns without imposing a new architectural style unnecessarily.
- - Use repositories only for domain-oriented persistence access.
- - Capture domain events as past-tense facts when occurrences matter to other
- behavior; do not equate domain events with event sourcing.
- - Update tests to express scenarios, outcomes, rejected operations, and
- invariants in the ubiquitous language.
- - Remove superseded terminology and implementations rather than retaining
- compatibility paths unless requested.
+ Writing rules:
- For refactoring, preserve externally required behavior while changing the model
- in small, verifiable steps. If the existing behavior contradicts the confirmed
- domain model, stop and ask which behavior is authoritative before changing it.
+ - One term, one meaning. Pick one name per concept and use it everywhere. Give
+ each overloaded word's distinct meanings their own names.
+ - State each rule once, in the one place that owns it. Elsewhere, refer to that
+ place instead of restating the rule.
+ - Define terms by behavior: what the concept does, permits, and forbids, and
+ how it differs from its neighbors. A synonym is not a definition.
+ - State rules in domain language, not in database tables, columns, endpoints,
+ or classes.
+ - Keep current-state content out: no implementation notes, migration status,
+ TODOs, open questions, or "not yet built" caveats. Report gaps between code
+ and model to the user in the conversation.
+ - When two neighboring terms are easily confused, say how they differ.
- ### 5. Validate With The Expert
+ ### 4. Make It Load
- Run the project's relevant tests and static checks. Then validate the result
- against the confirmed scenarios:
+ `DOMAIN.md` only guides agents that read it. If the repository's agent
+ instructions (`AGENTS.md`, `CLAUDE.md`, or equivalent) do not already load it,
+ suggest that the user add:
- - Does the implementation use the approved ubiquitous language?
- - Are the rules and invariants explicit and enforced at the right boundary?
- - Do tests cover normal cases, rejected actions, transitions, and exceptions?
- - Did persistence or framework details distort the model?
- - Did any approved assumption change during implementation?
+ - a reference that loads `DOMAIN.md` for every task
+ - a rule to use its language, follow its rules as written, and revise
+ `DOMAIN.md` first before introducing a concept, workflow, or policy absent
+ from it
- Summarize the implemented model and any remaining assumptions. Ask the user to
- validate material domain behavior that automated checks cannot establish.
+ Suggest the change; do not edit agent instructions unasked.
- ## Review Output
+ ## Consolidate
- For review-only requests, remain read-only unless the user later asks for fixes.
- Lead with findings ordered by behavioral risk and cite concrete files and lines.
- For each finding, state:
+ An actively revised `DOMAIN.md` accumulates redundancy and contradiction. On
+ request, or when the evidence step finds them, remove self-contained
+ inconsistencies and redundancies. The two are handled differently:
- - the observed implementation
- - the domain concept or rule that is implicit, duplicated, or contradicted
- - the consequence for behavior or model evolution
- - the smallest modeling change that would make it explicit
- - any domain question the user must answer before a fix
+ - **Redundancy**: the same rule or definition stated in more than one place.
+ Merge it into the one owning place and make the others refer to it. The
+ meaning must not change.
+ - **Inconsistency**: two statements that disagree, or one term used with two
+ meanings. Do not pick a side. Show the user both statements and ask which is
+ authoritative, then write the answer in the owning place.
- Do not report the absence of a tactical pattern by itself. Report a problem only
- when the current model obscures domain meaning, permits invalid behavior, leaks
- infrastructure, or makes change unnecessarily risky.
+ Read the whole document before editing. Finish by reporting what was merged and
+ which conflicts the user decided.
- ## Continuous Refinement
+ ## Revisit
- Treat the confirmed model as current, not final. When business behavior evolves:
+ Treat the confirmed model as current, not final. Revisit `DOMAIN.md` when
+ business behavior changes, when a task needs a concept the document lacks, or
+ when recurring confusion shows the language is not working:
1. Re-interview the user with concrete changed scenarios.
- 2. Update the ubiquitous language and model proposal.
- 3. Confirm the revision.
- 4. Refactor implementation and tests together.
- 5. Remove concepts and terms that no longer belong to the model.
+ 2. Revise the affected terms, model, and rules in place.
+ 3. Remove concepts and terms that no longer belong to the model.
+ 4. Have the user confirm the revision.
Model evolution is expected. Do not protect an obsolete model merely because it
- matches the current implementation.
+ matches the current implementation, and do not retreat from a confirmed model
+ merely because the implementation has not caught up.