Build a shared product vocabulary
Identify business terms that teams use differently and agree precise meanings. Keep short definitions separate from records of consequential design decisions.
How this works
Identify business terms that teams use differently and agree precise meanings. Keep short definitions separate from records of consequential design decisions. Use this when teams use the same word for different product concepts and the ambiguity causes incorrect requirements or reports. The output should be a small operational glossary supported by examples, not an encyclopedic dictionary.
Compare real business usage with documentation, data fields and code behavior. Propose canonical definitions, test them against concrete examples and obtain the relevant owners' decisions. Keep terminology definitions separate from consequential design tradeoffs and acceptance criteria.
Before you start
Existing glossary
Collect current definitions and known disputed terms.
Usage examples
Select relevant specifications, reports and implementation references.
Term owners
Identify business and engineering reviewers for the concepts involved.
Prepare the inputs
- terms
- Required
candidate words and contexts
Limit the review to terms that affect the current work.
- business_examples
- Required
concrete entities or events
Use anonymous examples with clear inclusion and exclusion cases.
- technical_references
- Required
fields, APIs or code locations
Do not assume a variable name establishes business meaning.
- existing_decisions
- Required
approved definitions and tradeoffs
Preserve version and owner.
Implementation, step by step
Collect conflicting usage
- Find where each term appears and summarize its meaning in context.
- Separate synonyms from genuinely different concepts.
Checkpoint: A usage matrix makes ambiguity visible.
Test concrete examples
- Ask whether each definition includes or excludes representative cases.
- Use counterexamples to expose hidden assumptions.
Checkpoint: The differences are expressed in observable terms.
Propose canonical language
- Draft a concise definition, aliases and boundaries for each concept.
- Avoid changing system behavior merely to make wording consistent.
Checkpoint: A proposed glossary is ready for owner review.
Record design implications
- Identify requirements or data interpretations affected by a chosen definition.
- Write consequential tradeoffs in a separate decision record.
Checkpoint: Terminology and design decisions remain distinct.
Publish the reviewed update
- Apply owner-confirmed definitions to the requested glossary location.
- List affected documents needing later updates and retain prior versions.
Checkpoint: The team has an accountable vocabulary.
Decisions along the way
One word describes two valid concepts
Create distinct terms rather than force a misleading single definition.
Code behavior conflicts with business intent
Record the discrepancy as a separate product decision.
Owners cannot agree
Mark the term unresolved and avoid using it unqualified in new specifications.
What you will produce
product-glossary.md
MarkdownA concise reviewed vocabulary.
Include: term · definition · aliases · examples · exclusions · owner
terminology-decisions.csv
CSVA separate record of consequential choices.
Include: term · conflict · decision · affected_artifacts · status
Check the result
- Test definitions against positive and negative examples.
- Verify business and technical owners reviewed affected concepts.
- Check aliases do not collapse distinct states.
- Ensure glossary text does not replace feature acceptance criteria.
When something goes wrong
Usage sample is too narrow
Collect examples from the affected teams before finalizing.
Definition becomes circular
Rewrite it in terms of observable entities or events.
Later implementation changes meaning
Flag the definition for review rather than silently update history.
A worked example
SYNTHETIC EXAMPLE · NOT A REPORTED BUSINESS RESULT
Request
Synthetic: resolve the word 'active customer.'
Inputs
Sales uses it for any signed account; reporting uses it for an account with a paid invoice in the last 90 days.
Expected result
Synthetic result: define signed_account and recently_paying_account separately, record the 90-day rule, and list reports needing clarification. Do not choose one definition solely because it appears in code.
Run a small pilot
Start small
Resolve five disputed terms within one product area.
Record the baseline
Record clarification cycles and inconsistent report interpretations.
Agree success criteria
Agree definition usefulness and example coverage before expanding the glossary.
Stop or revise
Stop applying a definition when its owners or business consequences are unresolved.
Keep the scope clear
- Terminology work does not authorize data migrations or product behavior changes.
- A glossary supports specifications but cannot substitute for tested requirements.
Check before using
Business owners approve meanings. A glossary complements specifications and must not replace acceptance criteria.
Business activities
- Maintain shared company knowledge
- Plan products and business changes
FROM A RECIPE TO YOUR WORKFLOW
Bring the company context together.
This workflow needs reliable inputs before it needs a better prompt. Moat8 Vault brings working information into a readable archive for the AI tools you use.
For this recipe: Product discussions and existing terminology · Examples, edge cases, and current behavior
Start with one recurring task, agree which sources to use, and review the first result with your team.
Discuss this workflow