> ## Documentation Index
> Fetch the complete documentation index at: https://docs.buildbetter.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Linear Evidence Tracker

> Tracked Linear issues receive evidence-backed comments that update automatically as new customer signals arrive

The Linear Evidence Tracker lives at the intersection of Topics, Tracked Items, and Linear. When a tracked Linear issue is connected to a topic (or attached as evidence directly), BuildBetter posts evidence-backed comments to the Linear issue and updates them as new customer signals arrive — keeping your engineering team in sync with what customers are actually saying.

<Info>
  Linear Evidence Tracker is in **early access**, rolled out alongside Topics.
</Info>

## What It Does

For any Linear issue you've marked as **tracked** in BuildBetter:

* Customer evidence (signals from calls, support, surveys, Topics) is collected against the issue
* A **comment thread** in Linear surfaces the evidence — quotes, customer names, sources, dates
* As new signals arrive that the matcher links to the same tracked issue, the comment **updates** with the new evidence
* The Linear issue's customer-impact picture stays current without anyone having to manually copy-paste

## What's in a Comment

The auto-generated Linear comment typically includes:

* A short summary of what customers are asking
* Quoted snippets from the underlying signals
* Customer / company names
* Source labels (Slack, Intercom, Call, Survey)
* Recency cues — when each signal arrived

The exact format adjusts to keep the comment readable as evidence grows.

## How Evidence Gets Attached

Evidence is attached via the **TrackedItemExtraction** model. Each row records:

* **`tracked_item_id`** — the tracked Linear issue's BuildBetter record
* **`extraction_id`** — the signal (extraction) being attached as evidence
* **`relationship`** — `primary` (directly about the issue) or `related` (tangential context)
* **`similarity_score`** — confidence the signal is relevant
* **`review_status`** — `suggested` (AI-proposed), `approved` (you confirmed), or `rejected`
* **`reviewed_by` / `reviewed_at`** — who acted on it and when

You review suggested evidence from the **Tracked Items** review surface; approval flows the signal into the live Linear comment.

## Linear Author Mapping

Per the 2026-05-05 release, you can map Linear users to BuildBetter teammates so ownership and attribution carry through accurately. The mapping screen shows the full workspace roster, highlights unmapped users, and distinguishes auto-mapped from manual mappings.

When a Linear issue is promoted or attached, the author mapping ensures:

* Assignees and DRIs reflect the real teammate, not a stale Linear handle
* Comment authorship and routing rules respect the mapping

## When Tracking Helps

* Engineering wants to see customer evidence inline with the issue, not in a separate tool
* Product wants to know which Linear issues already have enough customer evidence to prioritize
* Customer Success wants to know when their reported issue gets updates from other customers — and have those updates surface on the issue itself

## Limits

* Comment updates happen as new evidence is approved — not in real time. If you need an alert, configure topic notifications.
* The integration writes comments to Linear; it doesn't change Linear issue states or assignees on its own.
* Mapping is per-workspace; map once for the whole org.

<Tip>
  Pair the Linear Evidence Tracker with the [PR triage](./prs) flow — if a PR is in flight for a tracked Linear issue, both surfaces give you customer context next to the code.
</Tip>