Four categories of gaps
Every gap report evaluates a domain specification against four diagnostic categories. Each gap is a signal — not a verdict. The architect reads, investigates, and resolves.
Structural Gaps
Missing or malformed elements in the domain specification. Binary — the element exists or it does not.
Rule
Every DDD building block that is referenced must be fully defined. Every aggregate must protect at least one invariant. Every cross-context dependency must declare a relationship type.
What to look for
- Aggregates that are data containers (many fields, no invariants)
- Commands without preconditions
- Events that no one consumes
- Context relationships described in prose but not formally declared
- Missing entry paths described in requirements but absent from the specification
Examples from the veterinary clinic
SG-01 Aggregate with zero invariants — no consistency boundary to enforce
See this in the walkthrough →Heuristic Gaps
Patterns that violate established DDD principles. Each has a measurable threshold sourced from the DDD literature.
Rule
Thresholds are defaults, not dogma. They are calibrated from published sources and production experience. Override with rationale when your domain justifies it.
What to look for
- Aggregates doing too much (high command count, many responsibilities)
- Missing sagas where cross-aggregate coordination exists
- Policies chained in sequence — often a saga in disguise
- Contexts with too many aggregates (sign of a missing context boundary)
Heuristic Thresholds
| Heuristic | Default | Source | What it means |
|---|---|---|---|
| Aggregate command density | ≤ 6 | Vernon | Too many commands = too many reasons to change |
| Context term overlap | ≤ 3 | Evans | Shared terms = insufficient boundary |
| Saga step count | ≤ 5 | Practical | Beyond 5 = decomposition needed |
| Invariant coverage | ≥ 1 per aggregate | Evans | No invariants = no consistency boundary |
| Event fan-out | ≤ 8 per aggregate | Vernon | High fan-out = multiple concerns |
Examples from the veterinary clinic
HG-01 Sequential command pipeline on aggregate — suggests saga pattern
See this in the walkthrough →Language Gaps
Ambiguity or inconsistency in the ubiquitous language across the specification.
Rule
Every term must have exactly one meaning within its bounded context. Terms shared across contexts must have explicitly different definitions or identical definitions.
What to look for
- Terms that mean different things to different people
- Aggregate names that cause confusion with domain experts
- Implicit concepts — referenced but never named or defined
- Glossary gaps — terms used in commands/events but not formally defined
Examples from the veterinary clinic
LG-01 "Visit" vs. "Appointment" — semantic overlap at context boundary
See this in the walkthrough →LG-02 "Treatment" overloaded — means both single intervention and full episode
See this in the walkthrough →Decision Gaps
Architectural decisions that have been deferred or made without documented rationale.
Rule
Every boundary placement, aggregate decomposition, and relationship type must have a documented rationale. Deferred decisions must have an explicit scope note.
What to look for
- "Where does X live?" questions with no clear answer
- Boundaries drawn by convention rather than analysis
- Pricing, scheduling, or access control models referenced but never defined
- Scope assumptions that exist only in someone's head
Examples from the veterinary clinic
DG-01 Missing domain concept — referenced in requirements but absent from specification
See this in the walkthrough →DG-02 Pricing model undefined — service exists but data model is missing
See this in the walkthrough →