Purpose-first metrics: how to stop event taxonomy drift

A purpose-first product metric stores the decision behind the number as part of the metric definition. The metric still needs a stable key, source, aggregation type, status, and owner, but it is not valid until its purpose explains which product decision the metric informs. As of July 2026, Poolstatis requires this field for every metric and requires a separate goal for every funnel.

This rule looks small. It changes the way teams instrument products because it makes vague, redundant, and ownerless metrics harder to create. It also gives coding agents a semantic constraint that raw event catalogs do not provide.

The point is not to write a paragraph of governance text for every count. A useful purpose is one direct sentence. It should let a teammate answer three questions: Why does this number exist? Which decision can change because of it? What would make the definition obsolete?

What is a purpose-first metric?

A purpose-first metric is a reusable interpretation of product evidence with an explicit decision job. A good metric definition separates the stable business meaning from the event or property used to calculate it.

For example:

{
  "key": "activation_first_answer",
  "name": "Accounts reaching first product answer",
  "purpose": "Decide whether setup changes help verified accounts reach a typed analytics answer within 24 hours.",
  "type": "unique_actors",
  "source": {
    "event": "query.produced"
  },
  "status": "active",
  "owner": "growth"
}

The key is a durable reference for queries and funnels. The name is readable in product surfaces. The purpose names the setup decision and the first-value outcome. The type fixes the aggregation grain. The source identifies the immutable evidence. The status tells clients whether the definition is proposed, active, deprecated, or otherwise outside the trusted path.

Without the purpose, activation_first_answer sounds sensible but leaves material questions open. Does it evaluate onboarding copy, integration health, user intent, or agent setup? Is 24 hours part of the meaning? Should the team optimize the count of answers, unique accounts, or the share of eligible accounts? The purpose does not replace the full metric contract, but it prevents the definition from being treated as self-explanatory.

A purpose is not a target. “Reach 60% activation” describes an aspiration. “Decide whether setup changes help verified accounts reach a typed answer within 24 hours” describes the decision that the metric supports. Targets can change by quarter while the decision job remains stable.

Why event names are not enough

Event names describe implementation facts, while product metrics describe recurring interpretations. Treating an event name as a metric collapses these layers and creates taxonomy drift.

Consider button.clicked. The event states that a labelled interaction happened. It does not say whether the click represents acquisition, activation, retention, or accidental interaction. Even a more specific event such as workspace.created does not define the eligible population, aggregation grain, time window, or decision owner.

The gap becomes larger as a product evolves:

• one client emits signup.completed, another emits user.registered;
• the signup flow moves from one screen to three;
• workspace creation becomes automatic after email verification;
• test accounts and internal users need exclusion;
• a new pricing plan changes which accounts count as eligible;
• historical event payloads lack a property added in the current release.

If dashboards query events directly, each chart can resolve these changes differently. One chart keeps the old event, another unions two names, and a third filters on a current entity property. The organization ends up with several plausible activation rates.

A registry metric places the interpretation in one reviewable object. Query clients reference the metric key, not the raw event name. When the source changes, the definition and revision history explain what changed. Old immutable evidence remains intact.

Layer	Example	Change frequency	Primary question
Event	query.produced	Changes with instrumentation	What happened?
Entity state	account.plan = "team"	Changes with the product state	What is true now?
Metric	activation_first_answer	Changes with shared measurement meaning	What should we count for this decision?
Funnel	signup_to_first_answer	Changes with journey definition	Where does the intended journey lose actors?

This separation also improves debugging. When a value looks wrong, the team can inspect the metric source, then sample the underlying events, then check identity and properties. The investigation follows the contract instead of starting with a warehouse-wide search.

What belongs in a metric definition?

A metric definition should contain only the fields needed to preserve meaning, query behavior, lifecycle, and ownership. Extra prose makes review harder. Missing grain or source information makes the metric ambiguous.

The minimum practical set is:

1. Stable key. A machine-readable identifier used by queries, funnels, experiments, and configuration. Avoid release numbers or UI copy in the key.
2. Readable name. A short label that states the counted behavior or state.
3. Purpose. One sentence naming the decision and outcome the metric supports.
4. Type. The aggregation contract, such as event count, unique actors, state count, sum, or average.
5. Source. The registered event, entity field, or trusted property that produces the value.
6. Lifecycle status. A reviewable transition from proposal to active use and eventually to deprecation.
7. Owner. The team or role responsible for interpretation and changes.
8. Category and tags. A small classification layer for discovery, not a replacement for purpose.

The purpose should be specific enough to reject unrelated uses. “Measure activation” is too weak because almost any early product action could fit. “Decide whether setup changes help verified accounts reach a typed analytics answer within 24 hours” tells a reviewer that the metric should not be used as a general engagement measure.

The source should be narrow enough to implement consistently. If a metric requires a complex union, exclusion set, or identity rule, store that meaning in the definition or a versioned query contract. Do not leave the logic in one dashboard filter.

The owner should be accountable for semantics, not only for emitting the event. Engineering may own the SDK call, while growth or product owns the definition of activation. Naming the semantic owner makes review requests actionable.

What makes a purpose sentence useful?

A useful purpose sentence follows this shape:

Decide whether [product change or operating choice] improves [user or business outcome] for [eligible population or context].

The sentence does not have to use those exact words. It does need the decision and outcome. Add population or timing when they materially affect interpretation.

Good examples:

• Decide whether the shorter signup flow increases the share of verified accounts that create a first project within one session.
• Decide which integration fixes reduce rejected ingest batches for production environments.
• Decide whether reminder timing improves seven-day return among accounts that completed setup.

Weak examples:

• Track signup.
• Monitor user engagement.
• Important KPI for the dashboard.
• See how the feature performs.

The weak versions repeat the metric name, use a vague category, or name a reporting surface instead of a decision.

How should unregistered events be handled?

Unregistered events should be accepted as diagnostic facts, marked as outside the trusted metric contract, and surfaced through data-quality tools. Dropping them hides drift. Treating them as trusted evidence lets accidental instrumentation redefine product meaning.

Poolstatis uses this middle path. Ingest checks whether an event name is covered by the source of an active metric. If it is covered, the stored event receives registered=true. If it is not covered, the event is still accepted with registered=false, and an ingest warning records the mismatch.

This behavior supports three workflows:

1. New instrumentation verification. A developer can prove that an event reached the backend before the metric is approved.
2. Drift detection. A renamed or newly added event becomes visible without silently entering trend and funnel queries.
3. Debugging after deprecation. Historical and new occurrences remain inspectable even when an old metric is no longer active.

The registered flag is a quality signal, not a moral judgment about the event. Debug events, low-level system events, and future metric candidates can exist outside the active registry. The important rule is that production product conclusions should state whether their evidence is covered by active definitions.

An agent should react to unregistered evidence in a bounded way. It can sample events, compare them with active metric sources, and propose a definition or instrumentation fix. It should not activate every observed event. “Track everything just in case” turns the registry into another raw catalog.

How do purpose-first metrics improve agent queries?

Purpose-first metrics improve agent queries by narrowing candidate selection and making the returned number self-describing. A coding agent can match the user’s product question to metric purposes, categories, tags, and source types instead of guessing from similar event names.

Suppose a user asks: “Did the invite rewrite improve onboarding?” The project contains these metrics:

• signup_completed: purpose is to evaluate acquisition completion;
• invite_sent: purpose is to detect whether account owners reach collaboration setup;
• activation_first_answer: purpose is to evaluate whether setup changes lead to first product value;
• weekly_active_account: purpose is to monitor sustained account usage.

The word “onboarding” appears relevant to all four. The purposes reveal that activation_first_answer is the primary outcome, while invite_sent may be a diagnostic funnel step. The agent can then inspect the shared signup_to_first_answer funnel rather than inventing a new journey.

Metric purposes also improve answers after query execution. A response can include:

• the metric key and purpose;
• the query kind and date window;
• unique actor or event grain;
• registered coverage;
• filters and trusted property definitions;
• the observed movement and uncertainty;
• the next product decision.

This packet is more durable than “activation went up 8%.” A future reader can see what activation meant, why it was measured, and whether the same conclusion still applies.

Purpose does not guarantee correct metric selection. Agents still need guardrails, schema reads, and review. The field creates a semantic feature that can be tested. A metric with an empty or boilerplate purpose can be rejected before it becomes shared infrastructure.

When should a metric be deprecated?

A metric should be deprecated when its decision job no longer exists, its source can no longer represent the intended outcome, or a replacement definition has become the shared contract. Deprecation should preserve history and record a reason. Hard deletion should be reserved for mistakes that never became depended on.

Common deprecation triggers include:

• the product journey changed enough that the metric no longer represents the outcome;
• identity migration makes the previous unique-actor series incomparable;
• a metric duplicates a better reviewed definition;
• the decision owner no longer uses the metric;
• the source event was an implementation detail that cannot remain stable;
• legal or privacy boundaries remove a property required by the definition.

Do not deprecate a metric only because it moved in an unwanted direction. A bad result is not a bad definition.

The deprecation record should name the reason, effective date, and replacement key when one exists. Funnels and experiments that reference the old metric should be reviewed explicitly. New events may continue to arrive, but they should no longer receive registered coverage from an inactive metric source.

Metric revisions deserve the same care. A cosmetic name improvement can keep continuity. Changing actor grain, source meaning, eligibility, or aggregation type may require a new metric key because the series is no longer comparable. If a chart would need a visible break marker, the registry probably needs a new versioned definition.

Metric review checklist

Review a new or changed product metric against this list:

• The key is stable, specific, and independent from current UI copy.
• The name states the behavior or state being measured.
• The purpose names a product decision and an outcome.
• The eligible actor, account, or entity grain is clear.
• The source is a registered event, entity field, or trusted property.
• The aggregation type matches the intended question.
• Time boundaries and conversion windows are explicit where they affect meaning.
• The metric does not duplicate an active definition with different wording.
• An accountable semantic owner is named.
• The proposed-to-active transition is visible to human reviewers.
• Deprecation will preserve the definition, history, and replacement guidance.
• Queries can return registered coverage and enough context to reproduce the answer.

Purpose-first metrics are not a substitute for analysts or product judgment. They are shared infrastructure for keeping judgment attached to the number. Poolstatis documents the exact registry behavior in Purpose-first metrics, the instrumentation standard, and the goal-driven funnel contract.