Skip to main content

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.

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

Open the item

From any tab — Signals, PRs, Clusters, Tickets.
2

Click 'Promote to project'

In the detail-pane footer.
3

Item moves to /projects

The tracked item disappears from triage and appears in Projects. Its signals, PR links, and Linear ticket references come with it.

​
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:
TabWhat Bulk Promote Does
SignalsPromotes each tracked item directly.
PRsFetches each PR from GitHub, detects plan files, creates a tracked item with the PR auto-attached, then promotes it.
TicketsCreates 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.
Bulk promote is gated by the projects feature flag. If you don’t see the checkbox column, your workspace doesn’t have access yet.

​
Merge Duplicates

When two tracked items are about the same underlying request:
1

Open the source item

The one you want to merge into another.
2

Click 'Merge duplicate'

Opens the MergeDuplicateModal with a list of similar items (via the findSimilar API).
3

Pick a target

Click the item you want this one merged into.
4

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

Open the item

Any tracked item.
2

Click 'Correct classification'

Opens the CorrectionModal.
3

Pick what's wrong

  • Wrong type — pick the correct type from the dropdown
  • Should not be tracked — flag as a false positive (skip)
4

Add reason (optional)

Free-text reason. Optional but valuable as training signal.
5

Submit

Posts to trackedItemsControllerReportCorrection. The classifier learns from your feedback over time.
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.
1

Click 'Create ticket'

Opens the TrackedItemPushModal.
2

Edit the title

A draft title is pre-filled; edit as needed.
3

Review the description

The modal builds a markdown description from the item plus its linked signals.
4

Push

Creates the Linear issue and attaches it to the tracked item.
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.
1

Click 'Launch investigation'

Opens the LaunchInvestigationDialog.
2

Ask a question

Free text — e.g., “Are these complaints clustered around a specific customer segment?”
3

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
4

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.
This is the right exit when an item is interesting enough to investigate but the routing decision isn’t obvious yet.
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.