> ## 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.

# AI Routing

> Let the AI suggest where a triaged item belongs — attach to an existing project or create a new one, with editable preview and confidence score

AI Routing is the suggestion engine that proposes the best home for a tracked item, PR, cluster, topic, or ticket. It comes in two flavors: an inline banner for high-confidence suggestions, and a full modal for editing the proposal before applying.

## What the AI Decides

For each item, the agent looks at the item's title, description, and context and decides between two routing actions:

* **Attach** — link the item to an existing high-confidence project. Returns the project ID and reasoning.
* **Create** — propose a brand-new project, with an AI-generated title and description.

Both come with a **confidence score** (0–100) and **reasoning** explaining the choice.

## The Banner (Auto)

The `AiRouteSuggestionBanner` auto-loads on the detail pane for high-confidence **attach** suggestions. It's the fast path — one click to apply without opening a modal. Low-confidence suggestions and "create" suggestions stay collapsed in the banner so you can review.

## The Modal (Manual)

Click **AI route** in the detail-pane footer to open the full modal. The modal works for every item kind:

* **Signal** — typical triage path
* **PR** — promotes the PR into a project
* **Cluster** — promotes the whole cluster
* **Topic** — promotes a topic snapshot
* **Ticket** — promotes a Linear ticket

### What the Modal Shows

* **Suggestion** — Attach or Create
* **Confidence** — 0–100 score, color-coded
* **Reasoning** — why the agent chose this path
* **Editable fields** — title, description (and project pick if attaching)

You can edit anything before applying. The AI's choice is a starting point, not a commitment.

### Apply

Hits **Apply** and the routing happens atomically:

* For attach: the item's signals and metadata link to the target project; the tracked item disappears from triage
* For create: a new project is created with the (possibly edited) title and description; relevant extractions, topic snapshots, or Linear ticket references attach automatically

## Specialized Inputs

The modal accepts optional context to improve routing:

* **`ticketIdentifier`** / **`ticketUrl`** — if the item came from a Linear ticket, the routing can preserve the link
* **`extractionIds`** — for clusters or topics, the underlying signal IDs

These are wired automatically by the surfaces that open the modal — you don't have to think about them.

## When AI Routing Helps Most

* **High signal volume** — when the inbox is large, the banner gives you one-click answers for the obvious matches.
* **Cross-project deduplication** — the agent finds existing projects you might've missed in a manual search.
* **First-pass triage by non-experts** — anyone on the team can clear triage with the AI's recommendations; experts can review the audit log.

<Tip>
  If the AI suggests **Attach** but the existing project doesn't quite fit, edit the suggestion to **Create** in the modal — the agent's reasoning is preserved, and you start a new project with the AI's title and description as a draft.
</Tip>