Six months into a project, domain experts start using a brand-new term, 'Chargeback Hold', that doesn't exist anywhere in the current codebase or vocabulary. Walk through how a team should evolve its shared domain language and the code model together when this happens.
answer
- new term = model breakthrough, treat as design event
- ask trigger/duration/resolution before coding
- decide shape: new state, new entity, or new event
- don't bolt a boolean onto an existing field
- ubiquitous-language debt compounds like tech debt
basics
~20 sDon't just bolt on a field or flag for the new idea. Go talk to the domain experts about what 'Chargeback Hold' really means and why it matters, then change the code's actual shape — new class, new state, new rules — to represent it properly, and use that exact name everywhere afterward.
solid answer
~50 sNew vocabulary appearing mid-project is normal — it means the team's understanding of the domain is deepening, often called 'model breakthrough' in DDD. The right response is to treat it as a modeling event, not just a naming task: get domain experts to explain what triggers a Chargeback Hold, what it prevents, how it resolves, and whether it's a new state on an existing entity (e.g., an Order transitioning into a ChargebackHold state) or a genuinely new concept (a separate entity tracking hold reason, expiry, and linked disputes). Only after that conversation should the team refactor the code to introduce the term explicitly — as a class, an enum value, or a domain event — rather than quietly repurposing an existing generic field like status or flags. The trade-off is that this refactor competes with feature work for time; teams that defer it risk the new term becoming shadow knowledge that lives only in Slack and stand-ups while the code silently misrepresents the domain.
go deeper
Can recognize that a new word from stakeholders that doesn't appear anywhere in the code is a signal something needs to change; not expected to design the resulting model themselves.
Proposes going back to the domain expert to clarify the new term and can suggest a reasonable first-pass field or state change, though may not spot subtler shape questions like stacking holds.
Runs the clarifying conversation, correctly judges whether the new concept needs a new entity, state, or event, and can explain why a shortcut like a boolean flag would misrepresent the domain.
Recognizes recurring model-breakthrough moments as evidence the team's domain-conversation cadence is too infrequent, and adjusts team process (e.g., regular modeling sessions) so new vocabulary surfaces and gets addressed continuously rather than in occasional large refactors.
## What new vocabulary signals In Domain-Driven Design, the appearance of new vocabulary mid-project — a domain expert starts saying 'Chargeback Hold' where six months ago they didn't — is a normal and expected event, sometimes called a **model breakthrough**: it signals that the team's collective understanding of the domain has deepened, usually because a real scenario (an actual dispute, an actual regulatory question) forced everyone to articulate a distinction that was previously implicit or unhandled. ## The three steps for responding The mechanism for responding correctly has three steps. 1. **First, capture the term in a real conversation** rather than a hallway aside: ask the domain expert directly what triggers a Chargeback Hold, what business outcome it prevents (e.g., blocking a merchant payout while a disputed charge is investigated), how long it lasts, and how it resolves (released, escalated, converted to a permanent chargeback). 2. **Second, decide the shape the new concept takes in the model** — is it a new state in an existing entity's lifecycle (an `Order` or `Payout` gaining a `ChargebackHold` state alongside `Pending/Completed/Cancelled`), a standalone entity in its own right (a `ChargebackHold` record with its own id, reason, expiry, and linked dispute reference), or a domain event (`ChargebackHoldPlaced`, raised when a dispute is opened, consumed by whatever process freezes the payout)? 3. **Third, only after that decision, refactor the code** so the term appears explicitly — as a class name, an enum value, or an event name — rather than being absorbed into an existing generic field. ## Why a boolean flag is the wrong shortcut The reason this process matters, rather than just adding a boolean flag, is that the alternative is silent, compounding **model decay**. The path of least resistance under deadline pressure is to add `isOnHold: Boolean` to the existing `Order` class and move on; this technically 'handles' the new requirement but throws away everything the domain experts actually told you: - why it's on hold, - for how long, - what happens next, - who can release it. Every future question about holds ('can a hold be partial, only some line items?', 'does a hold block a refund too?') now has nowhere natural to live in the model, and engineers either bolt on more booleans and nullable fields (a pattern sometimes called a boolean/string soup) or have to reverse-engineer the real business rules from scattered conditionals months later when a bug or an audit forces the question. ## The trade-off The trade-off a team is actually making is **refactor time now versus compounding confusion later**. Modeling the new concept properly — a real `ChargebackHold` class or a documented state transition — takes real design and implementation time that competes directly with shipping the next feature, and it's tempting to defer it, especially if the current sprint doesn't strictly require handling every edge case the domain expert mentioned. Teams that consistently defer this work accumulate what's sometimes called **'ubiquitous language debt'**: a growing gap between what people say in meetings and what the code actually represents, which behaves like technical debt but is harder to detect with static tools since nothing is 'broken' — the code runs fine, it's just quietly wrong about what it means. ## Failure modes Failure modes are recognizable in production. 1. **The most common is that the new term becomes 'shadow knowledge'**: everyone in meetings says 'Chargeback Hold' and understands what it means, but the code has no concept with that name, so any engineer reading the code cold has no way to discover the concept exists — they'd have to already know to ask about it. This causes duplicated, inconsistent implementations: one engineer adds an `isOnHold` flag to `Order`, another engineer six months later, unaware of the first, adds a separate `holdStatus` field to `Payout` to handle what's conceptually the same thing, and now the business rule for 'is this hold still active' exists in two disagreeing places. 2. **Another failure mode is that when the concept finally does get modeled properly**, it requires a large, risky refactor across every place the ad hoc boolean was checked, which is exactly the expensive rename-and-restructure that early, disciplined modeling was meant to avoid. ## A worked scenario A realistic worked scenario: a payments team hears 'Chargeback Hold' for the first time when a dispute-resolution specialist explains that when a customer disputes a charge, the merchant's next payout must be frozen for the disputed amount until the dispute resolves, and if the merchant disputes multiple times, holds should stack rather than overwrite each other. That last detail — holds stacking — immediately rules out a single `isOnHold` boolean on `Payout`, since a boolean can't represent multiple simultaneous holds with independent amounts and expiries. The team instead introduces a `ChargebackHold` entity (amount, reason, linked dispute id, placed-at, released-at) with a one-to-many relationship to `Payout`, and a `ChargebackHoldPlaced` domain event that the payout-calculation process consumes to reduce the available payout amount. Because the team had the domain conversation before writing code, the model was right the first time, and 'Chargeback Hold' now means the same thing in the standup, the ticket, and the class name.
- What's a concrete sign that a new term should become a full entity rather than just a new enum value on an existing entity?If the new concept has its own independent lifecycle, its own attributes that don't apply to the parent entity (like a hold's amount, reason, and expiry), or if there can legitimately be more than one active at a time on the same parent (holds stacking), that points to a standalone entity rather than a single enum field, which can only represent one state at a time.
- How do you avoid a big-bang refactor every time a new term shows up?By treating language changes as continuous, incremental refactoring rather than deferred batches — renaming and reshaping as soon as a term is confirmed, even if it's a small change, so the gap between code and vocabulary never has time to grow large enough to require a risky wide-reaching rewrite.
- Who should be involved in the conversation about what a new term like 'Chargeback Hold' really means?The domain expert who introduced the term (here, likely someone in dispute resolution or risk operations), plus whichever engineers own the affected part of the model (payments and payouts); it shouldn't be a single engineer guessing alone, since the risk is exactly that an engineer's assumption about the term diverges from what the domain expert actually meant.
Like a hospital adopting a new diagnostic category after doctors start distinguishing a condition they used to lump under a generic label — they don't just add a checkbox to the old form; they redesign the intake process, because the new category has its own causes, treatments, and follow-up that the old form has no room for.
saying these in an interview costs you the question
- Immediately proposes adding a boolean/status field without asking what the term actually means
- Doesn't mention going back to talk to the domain expert who introduced the term
- Treats new vocabulary as scope creep to reject rather than a signal the model needs updating
- Can't distinguish when a new term needs a new entity versus just a new enum value
- Assumes the team can defer the modeling work indefinitely with no compounding cost