The Reasoning Trail

The Reasoning Trail is a first-class object alongside the metric definition itself. It is not a comments thread bolted to a wiki page. It is a structured surface with intent (question, proposal, objection, clarification, decision rationale), resolution state, and an explicit boundary between human-only conversation and notes pinned for agent context.

Pinning is the load-bearing act. A note in the trail is a human talking to a human; a pinned note is a human curating the institutional fact base an AI agent will read at inference time. The two audiences share the same surface so the curation decision happens where the conversation actually lives.

An agent fetches the metric’s contract envelope fromGET /api/v1/metrics/{id}/contractand reads the Reasoning Trail through four fields: the count of threads and messages (signal that conversation exists), the array of admin-pinnedagent_context_notes(the curated facts), and thediscourse_summary(open-objection and open-proposal counts plus last-activity timestamp).

Together those four fields let the agent answer with a caveat that reflects reality: “the canonical definition excludes internal test orgs by team decision in 2026-Q1; one open objection is unresolved about whether free-tier customers should be reported separately.” That is a categorically different answer than the same agent reading the SQL alone.

See the contract envelope

On the metric detail page, the Reasoning Trail lives on theNotestab. Anyone in the workspace can add a note. The composer asks the author to choose an intent — question, proposal, objection, clarification, or decision rationale — so the resulting thread is structured rather than free-form.

Workspace admins and owners can pin a message for AI context. Pinning carries weight: it commits a piece of human conversation to the agent-readable contract for the metric. The Notes UI shows a count next to the pin button so the curator always knows how much of the shared per-metric pin safety limit remains.

A useful Reasoning Trail is selective. It should not become a raw transcript of every Slack debate or a second requirements doc. The highest-value entries are the decisions that explain why a metric differs from an intuitive definition, the objections that have not been resolved yet, and the clarifications an analyst or agent would otherwise rediscover by asking a teammate.

For a revenue metric, that might mean pinning the finance decision to exclude internal test orgs, a sales-team proposal to split self-serve and sales-led accounts, and the open objection that free-tier usage should not be blended into an ARR-facing view. For an operational metric, it might mean the agreed time-zone boundary, the warehouse source that is authoritative, and a temporary caveat while a pipeline is being repaired.

• Pin decision rationale when it changes how a consumer should interpret the metric.
• Leave unresolved objections visible when the metric is still approved but carries a material caveat.
• Prefer concise notes with concrete dates, source systems, and owner names over broad commentary.

The trail separates conversation state from metric approval state. A metric can be released while an objection remains open, as long as the owner is comfortable exposing that caveat to downstream consumers. That distinction matters for AI systems: approval says the metric can be used; the trail says how much confidence and nuance should travel with the answer.

Admin pinning is also intentionally permissioned. A workspace member can ask a question or propose a change, but only owners and admins can promote a message into agent context. This keeps the agent-readable corpus small, reviewed, and tied to the same governance model as definition releases. When context ages out, teams should unpin it rather than letting stale guidance remain in the contract envelope.