Keep contracts and language consistent across the product

Check the language used across APIs, events, reports and user interfaces. Teams may use different names for one concept or reuse one name for concepts with different behaviour. Each new dependency makes the mismatch harder to change.

Create a small glossary for terms that carry product behaviour. Define words such as account, member, owner, active, cancelled, completed and archived only where they have a shared meaning. Include disallowed or misleading synonyms when those are causing errors. The glossary should point to the source that defines lifecycle and permissions rather than trying to duplicate every rule.

For shared data, name the source of truth and the permitted copies. A service may own the current subscription state while other components keep a read model. Document how copies update, how staleness is handled and which system resolves disagreement. Without this, each copy slowly becomes a candidate authority.

Version contracts when consumers cannot change together. Database migrations, APIs and events need a period where deployment order does not corrupt or misinterpret information. Prefer additive changes first where practical. Introduce the new field or event, update consumers, verify use, then remove the old form through a separate decision.

Include behavioural compatibility, not only schema compatibility. An API can return the same fields while changing when a status becomes final. A background task can publish the same event after moving it earlier in a transaction. Consumers may depend on timing and guarantees that were never written into the schema.

User-facing consistency needs review too. If one area calls a state "paused" and another calls the same state "inactive", people will form different expectations about access and recovery. Product copy should follow the shared meaning, with deliberate exceptions documented when the audience requires different language.

Automated checks can protect parts of the contract. Schema validation, consumer tests, migration tests and shared fixtures can catch incompatible shapes and state transitions. The decision record and human review still need to establish whether a changed concept is appropriate.

When a team finds an existing inconsistency, avoid a broad cleanup without an inventory. Identify each use, choose the intended meaning, plan compatibility and give operators a way to reconcile old records. Renaming a value in code does not repair data or downstream assumptions by itself.