Before: Two dashboards use the same metric name with different filters.
One metric keeps one definition
The formula, grain, exclusions and owner travel together into every scoped task.
HINT for Data & BI Analysts
Your assistant writes SQL fast. HINT keeps every metric on its definition.
HINT keeps metric definitions, data grain, source columns and caveats in plain-text notes beside dashboards and queries. Your assistant reads the context for this domain before changing a number.
The package is named for the role: @openhint/hintbook-data-analyst.
Where it helps
Three situations your team will recognize
Before: A query references a plausible column that is not in the source.
SQL stays inside declared schemas
Unknown fields become schema questions instead of silently broken joins.
Before: A fresh-looking chart hides stale or partial data.
Caveats travel with the number
Freshness, quality limits and interpretation notes arrive beside the metric rather than in a forgotten wiki page.
See it
A real sales metric from the demo
The Dunder Mifflin BI demo grounds the sales metric in an approved source.
demo-dunder-mifflin-bi/domains/sales/metrics.md.hint ↗
# read Approved source
../../sources/approved.md
# metric sales-1 {#data_analyst_demo}
Approved metric grounded in SRC-1.
# never Invented detailsWhat your assistant does next
It uses the metric's declared source and definition, checks referenced columns, and carries caveats into the answer.
What your AI assistant receives
<metric name="sales-1">
Approved metric grounded in SRC-1.
</metric>
<never name="Invented details">…</never>Your boundaries stay visible
What it will never do
- Invent data, columns, freshness or metric definitions.
- Change a metric's grain or exclusions without a decision.
- Present an estimate without its caveat and source.
FAQ
Questions data & bi analysts ask
Does this replace dbt or LookML?
No. It supplies intent and constraints to assistants working with those systems and can point to their definitions as sources.
Does it validate SQL?
It can require declared sources and checks, but execution and warehouse validation remain in your analytics stack.
Can different domains define different metrics?
Yes. Folder scope separates domain-specific definitions while shared policies can sit above them.
For your technical colleague
The vocabulary
A hintbook is a vocabulary for your profession—installed, not written by you.
metric- Defines a measure, formula, grain and owner.
grain- States what one row or observation represents.
formula- Records the exact calculation for a metric.
dimension- Names an approved axis for grouping or filtering.
filter- Sets an approved inclusion or exclusion rule.
freshness- States how current the source must be.
quality- Defines an observable data-quality expectation.
dashboard- Sets the audience and purpose of a BI surface.
Manual setup
Bootstrap is read-only: it prints instructions for the assistant. The assistant performs the installation.
npm install -g @openhint/cli
hint config
hint add @openhint/hintbook-data-analyst
hint apply
hint verify domains/sales/metrics.md
hint emit domains/sales/metrics.md