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

# Promote, Merge, & Correct

> How items leave triage — promotion to /projects, merging duplicates, correcting misclassifications

Every tracked item in Triage eventually leaves it. There are three primary exits: promotion, merging, and correction (skip). Each has both single-item and bulk variants.

## Promote to Project

The most common exit. A tracked item with `in_triage: true` becomes a project with `in_triage: false` and `status: in_progress`.

<Steps>
  <Step title="Open the item">
    From any tab — Signals, PRs, Clusters, Tickets.
  </Step>

  <Step title="Click 'Promote to project'">
    In the detail-pane footer.
  </Step>

  <Step title="Item moves to /projects">
    The tracked item disappears from triage and appears in [Projects](../Projects/overview). Its signals, PR links, and Linear ticket references come with it.
  </Step>
</Steps>

### Bulk Promote

Select multiple items with checkboxes, then click **Promote N**. The bulk path uses a bounded-concurrency queue (max 3 parallel) so it's safe to run on dozens of items at a time.

Each tab has subtly different bulk-promote behavior:

| Tab         | What Bulk Promote Does                                                                                                                  |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| **Signals** | Promotes each tracked item directly.                                                                                                    |
| **PRs**     | Fetches each PR from GitHub, detects plan files, creates a tracked item with the PR auto-attached, then promotes it.                    |
| **Tickets** | Creates a tracked item per Linear ticket with the ticket auto-attached, then promotes. Already-linked tickets are skipped with a toast. |

After bulk promotion, a toast reports successes and failures — you can inspect any errors per item.

<Info>
  Bulk promote is gated by the `projects` feature flag. If you don't see the checkbox column, your workspace doesn't have access yet.
</Info>

## Merge Duplicates

When two tracked items are about the same underlying request:

<Steps>
  <Step title="Open the source item">
    The one you want to merge **into** another.
  </Step>

  <Step title="Click 'Merge duplicate'">
    Opens the `MergeDuplicateModal` with a list of similar items (via the `findSimilar` API).
  </Step>

  <Step title="Pick a target">
    Click the item you want this one merged **into**.
  </Step>

  <Step title="Confirm">
    The source item is marked as a duplicate; its signals re-attach to the target. The merge event is logged in the target's timeline.
  </Step>
</Steps>

Both items remain in the database — the source is flagged as a duplicate, not deleted. This preserves history.

## Correct Classification

Tell BuildBetter when an item shouldn't be in triage.

<Steps>
  <Step title="Open the item">
    Any tracked item.
  </Step>

  <Step title="Click 'Correct classification'">
    Opens the `CorrectionModal`.
  </Step>

  <Step title="Pick what's wrong">
    * **Wrong type** — pick the correct type from the dropdown
    * **Should not be tracked** — flag as a false positive (skip)
  </Step>

  <Step title="Add reason (optional)">
    Free-text reason. Optional but valuable as training signal.
  </Step>

  <Step title="Submit">
    Posts to `trackedItemsControllerReportCorrection`. The classifier learns from your feedback over time.
  </Step>
</Steps>

Skipped items leave triage immediately. The system uses your corrections to reduce future false positives.

## Push to Linear

If a tracked item should live in Linear (not as a BuildBetter project), push it.

<Steps>
  <Step title="Click 'Create ticket'">
    Opens the `TrackedItemPushModal`.
  </Step>

  <Step title="Edit the title">
    A draft title is pre-filled; edit as needed.
  </Step>

  <Step title="Review the description">
    The modal builds a markdown description from the item plus its linked signals.
  </Step>

  <Step title="Push">
    Creates the Linear issue and attaches it to the tracked item.
  </Step>
</Steps>

After push, the **Create ticket** button changes to **View ticket** with a link out to Linear.

## Launch Investigation

Kick off a Signals Background Agent run for items that need deeper analysis before any routing decision.

<Steps>
  <Step title="Click 'Launch investigation'">
    Opens the `LaunchInvestigationDialog`.
  </Step>

  <Step title="Ask a question">
    Free text — e.g., *"Are these complaints clustered around a specific customer segment?"*
  </Step>

  <Step title="Pick the action policy">
    * **Suggest only** — the agent surfaces suggestions; you approve before any state changes
    * **Approval required** — the agent can act after explicit approval at each step
  </Step>

  <Step title="Launch">
    Creates a `signal_agent_run` row with scope metadata and enqueues the chat-analysis worker. Polling and approval continue in the AI Chat surface.
  </Step>
</Steps>

This is the right exit when an item is interesting enough to investigate but the routing decision isn't obvious yet.

<Tip>
  Use **Correct → Should not be tracked** generously. The cost of a false positive (an irrelevant item in your inbox) is far higher than the cost of correcting it once.
</Tip>