AI agent issues

A Linear-style tracker for data problems — AI-filed findings and human-filed issues on one board, with one-click fixes for semantic layer and project context gaps.

Availability: Issues is a Beta feature available on Enterprise and Cloud Pro plans. It is off by default and must be enabled by an organization admin.

The Issues board is where data problems get tracked. Two things land on the same board:

• AI-filed findings — every AI agent turn is scanned in the background; likely-wrong answers are grouped by root cause and filed automatically.
• Human-filed issues — anyone with access can report a problem straight from a chart, dashboard, tile, or the board itself.

Each issue has a priority, an assignee, an activity feed, and — where applicable — a one-click writeback that opens a pull request against your dbt project or your shared project context file.

When to use it

Turn Issues on once you have agents in regular use and want a shared queue for data-quality work. It’s most useful when:

• Users ask the same kind of question repeatedly and the agent struggles
• You want to keep dbt metadata and agent instructions tight as your data model evolves
• You’re rolling agents out to a wider audience and want admin-level visibility into quality
• You want a single place to triage data problems users spot in dashboards or charts

If you’re still setting your first agent up, start with agent setup and evaluations first — Issues works best once there’s real usage to learn from.

Enabling Issues

Issues is opt-in. Until an admin enables it, no agent turns are processed and no findings are collected.

1. Go to Settings → Ask AI → General.
2. Toggle Review AI agent turns on.

Once enabled, future agent turns are scanned in the background and human-filed issues can be reported from anywhere in the app. Existing threads are not back-filled.

To stop AI scanning, toggle the setting off. Previously collected issues remain on the board until you act on or dismiss them.

Opening the board

Open Settings → Ask AI → Issues to see the board.

The Ask AI button in the navbar is the fast path: when there are open issues it previews recent findings; when the board is empty it shows a small dropdown that links straight to the Issues board so newly-filed manual issues are always reachable.

Cards on the board are grouped by status lane (To Do, In Progress, Done) and each card shows its priority, assignee, and category badge. Click a card to open the issue detail modal.

How issues get onto the board

AI-filed findings

With the setting enabled, Lightdash scans every AI agent turn for signs the answer was probably wrong — a missing metric, an ambiguous field, a gap in your project context — and files an issue for each root cause it identifies.

Before filing, the classifier checks the board’s existing issues and, if the same underlying problem is already tracked, attaches the new evidence to that issue instead of opening a duplicate. Recurring findings bump the Recurs N× tag on the existing card.

Slack notifications (if configured) only fire when a new issue is opened. Recurrences accrue silently on the existing card so a chatty problem doesn’t spam the channel — check the board for the latest state.

AI findings are opened in the same lane your triage workflow uses (existing findings behavior is unchanged).

Human-filed issues

Any organization admin with AI agents enabled can file an issue from several places:

• The New issue button on the Issues board.
• The Create issue item in the 3-dot menu on a dashboard header.
• The Create issue item in the 3-dot menu on a chart or explore header.
• The Create issue item in the 3-dot menu on a dashboard chart tile.
• The Create issue action on a resource row in Spaces and Home.

When you file from a chart, dashboard, or tile, the modal opens with the content’s project locked in and shows a Reported from <chart/dashboard> chip so the provenance travels with the issue. Manual issues land in the To Do lane.

Filing an issue

The Create issue modal captures:

Field	Description
Title	Short summary of the problem.
Description	Markdown-supported detail. Doubles as the “desired outcome” the writeback agent reads.
Project	The project the issue belongs to. Locked when filed from a chart, dashboard, or tile.
Priority	urgent, high, medium, low, or none.
Assignee	The person responsible for triaging the issue.
Agent	The AI agent that owns the affected models. Click Suggest to pre-select the best-fit agent — Lightdash uses the same AI router as Ask AI, routing your title and description to pick an agent and showing its reasoning as a hint. Clearing the agent clears the hint.
Related explores	Multi-select of the explores the issue is about. Pre-seeded with the chart’s base explore when filed from a chart. Feeds the writeback prompt so the agent edits the right YAML.

Submit and the issue appears on the board in To Do, with the author recorded as the creator.

The issue detail modal

Clicking a card opens a focused modal with a metadata rail (status, priority, assignee, agent, project) and a chronological activity feed that merges issue events with any existing writeback events:

• created
• status_changed
• assignee_changed
• priority_changed
• comment_added
• recurred

You can change status, priority, and assignee inline; each change writes an event to the feed with its author. Comments are supported and appear inline in the feed.

For AI-filed findings, the modal also has an Evidence section that shows the curated excerpts the classifier actually cited — not the full agent thread. A Read full conversation action opens the source thread in a stacked modal (or in a new tab) if you need the wider context. Findings also show an affected-target chip and a Recurs N× tag next to the category badge, and — if writeback is blocked — a plain-language note explaining why (for example, that a GitHub or GitLab connection is required).

Fixing an issue with writeback

For each issue, Lightdash proposes the smallest change that would prevent it:

• Semantic layer fixes open a pull request against your dbt project (rename a field, add a description, add a metric).
• Project context fixes add a short note to a shared file that your agents read before answering future questions.

Writeback runs the same way whether the issue was AI-filed or human-filed. A manual issue is eligible for writeback when it has:

• a root cause of semantic layer or project context,
• a project, and
• an assigned agent.

For manual issues, the Related explores you picked when filing are passed into the writeback prompt so the agent starts from the right model instead of guessing from the description.

Issue type	What it means	How to fix
Semantic layer	A field, metric, or description is missing, ambiguous, or wrong in your dbt project.	Run writeback to open a pull request against your dbt repository.
Project context	Your agents are missing background knowledge to answer reliably (e.g. which table to use for “active customers”).	Run writeback to add a note your agents read before answering.

The lightdash.project_context.yml file

Project context fixes don’t touch your dbt models. Instead, they write to a separate file — lightdash.project_context.yml — that lives next to lightdash.config.yml inside your dbt project directory. Your AI agents read it before they answer, so notes you add here change future behavior without changing the semantic layer.

The file is committed to your dbt repo and travels with the rest of your project metadata. The first time a project context fix runs, it creates the file (with a header explaining what it’s for) and opens a pull request. Subsequent fixes add or update entries in the same file.

The full JSON Schema is published at lightdash-project-context-1.0.json — point your editor at it for autocomplete and validation.

File shape

lightdash.project_context.yml

version: 1
entries:
  - id: aov
    kind: definition
    content: "AOV means average order value — total revenue divided by number of orders in the period."
    terms: ["AOV", "average order value"]
    objects: []
  - id: active-customers-table
    kind: context
    content: "Use `fct_customer_activity` for active-customer questions; `dim_customers` is a slowly-changing dimension and double-counts churned customers."
    terms: ["active customers"]
    objects: ["fct_customer_activity", "dim_customers"]

The top-level document is { version, entries }. A bare array of entries is also accepted for backward compatibility, but new files are written in the canonical shape.

Top-level properties

Property	Type	Required	Description
version	number	yes	Schema version. Currently always 1. Bumping this is the escape hatch for a future breaking change.
entries	array	yes	The list of context entries. May be empty.

Entry properties

Each item in entries is a single self-contained fact your agents should know.

Property	Type	Required	Description
kind	"definition" | "context"	yes	How the entry is retrieved. Use definition for term-triggered facts (acronyms, vocabulary, “X means Y”). Use context for object-scoped guidance (routing rules, join rules, durable facts about a model).
content	string	yes	One self-contained sentence. This is what the agent reads. Keep it short and unambiguous.
id	string	no	Stable identifier used to update the entry later. Optional — Lightdash derives one from terms[0] (or content) at ingest if you omit it, suffixing on collision. Provide an explicit id if you want to hand-edit later without worrying about churn.
terms	string[]	no	Prompt-facing trigger words and phrases. Used to surface definition entries when a user’s question mentions one of them. Defaults to [].
objects	string[]	no	Semantic objects (models, fields, joins) this entry concerns. Used to surface context entries when the agent is reasoning about one of these objects. Defaults to [].

Unknown keys on an entry are preserved on round-trip, so a field a newer Lightdash version adds won’t be silently dropped if you edit the file by hand.

Editing the file

You can edit lightdash.project_context.yml directly — it’s a normal file in your dbt repo. The Issues flow is designed to coexist with manual edits: writeback uses the GitHub API to merge a single entry at a time, preserving comments, quoting, and key order in the rest of the file, so the resulting diff is just the changed entry.

If you do edit by hand, the same validation rules apply: invalid files surface schema-backed errors at ingest time.

Project context vs. semantic layer fixes

Both kinds of fix open a pull request, but they change different things and have different review costs.

	Semantic layer fix	Project context fix
What it changes	Your dbt model YAML — renames a field, adds a description, adds a metric, fixes a join.	A single entry in lightdash.project_context.yml.
Who else sees the change	Everyone querying the model, in Lightdash and downstream.	AI agents only.
How the PR is built	A writeback agent runs in a sandbox against your dbt project and proposes the edit.	Deterministic merge into the YAML file via the GitHub API — no sandbox.
When to use it	The data model itself is wrong, ambiguous, or under-described. The fix would help SQL users too, not just the agent.	The data model is fine, but the agent is missing background knowledge — terminology, which table to prefer, business rules that aren’t expressible as dbt metadata.
Reversibility	Same as any dbt change — revert the PR.	Delete or edit the entry in lightdash.project_context.yml.

A rule of thumb: if a new analyst joining the team would also benefit from the change, it’s probably a semantic layer fix. If only the agent needs to know it, it’s project context.

Privacy and data handling

• Issues runs against agent turns inside your organization only.
• Issues and findings are stored in Lightdash alongside your other agent data and respect your existing project and admin permissions.
• Disabling the toggle stops new AI scanning immediately; it does not delete previously collected issues.

Related

• Evaluations — run a fixed set of prompts against your agent and grade the answers.
• AI writeback — let an agent open a dbt pull request from chat.
• Autopilot — scheduled agent that cleans up content and flags issues for review.