Choosing where knowledge goes
What belongs in company-wide guidance, a domain guide, and a semantic model?
Put broad rules in company-wide guidance: what the business does, data conventions, recurring mistakes, and preferences that apply across many questions. A domain guide holds the detail for one area of work, including definitions, sources, joins, filters, and how to interpret results. A semantic model holds established measures, dimensions, and relationships that should be calculated the same way each time. The guide can explain when to use a measure from the model.
Can a small team keep everything in one Markdown file?
Usually, no. A rule about one subject does not need to follow every conversation. Keep the short, widely applicable rules separate from detailed guidance for particular topics. Then the agent can retrieve what the question needs without carrying every definition at once.
What should go in company-wide context?
Start with the business, where production data lives, conventions that apply across datasets, mistakes you see repeatedly, and how answers should be checked and presented. Keep it short enough to be useful for almost every question. The detailed definition of one metric belongs with that domain or in a semantic model.
How do I make a domain guide easy for an agent to find?
Give it a clear name and short description using the words people actually ask with, including common names and synonyms for the subject. Put the detailed instructions in the body. Then ask a representative question and inspect whether the agent found and used the guide. Publishing it alone does not prove it will be retrieved.
Definitions and decisions
What should I document for an important metric?
Write down who or what is counted, what qualifies, the reporting window, exclusions, source, and calculation. Add the checks that make a comparison trustworthy, such as data coverage or a change in tracking. If people will break the metric down by team, country, or product, explain how each record is assigned and how the pieces relate to the total.
When is a semantic model worth building?
When a calculation or relationship is established and people should reuse it. The model defines the source, grain, measures, dimensions, and relationships. An open-ended question such as “why did this change?” may still need a domain guide and additional analysis. You do not need to formalize every possible question before someone can investigate it.
If the model has the calculation, what does the guide add?
The model calculates. The guide explains which calculation to use for a question, which comparisons make sense, and what caveats matter. That distinction lets you maintain one approved calculation without trying to fit every business instruction into the formula.
Where should a method for “why did this change?” questions live?
Usually in a guide for the subject or type of investigation. It can tell the agent to check the definition and data coverage, compare the right periods, and look at relevant groups before naming a cause. Keep the method open enough that the question can lead somewhere you did not anticipate.
How should we handle a metric that includes an estimate?
Keep measured and estimated values distinct. State how the estimate is made, which inputs it needs, where it can be used, and what to do when an input is missing. If the estimate only makes sense at the company level, do not divide it among individual users or segments. Label the result so no one mistakes an estimate for an observed count.
Should an agent ask for clarification or send a question to a person?
Yes, when the answer depends on a term that has more than one meaning or a rule nobody has approved. For example, “exclude internal users” sounds simple until you ask which accounts are internal. Give the agent the approved rule, or tell it to ask. A human owner should make a new business decision; the agent should not invent one.