How issues are filed
Lucid writes every issue: after an alert fires, from a Failures row, from an eval's finding, or when you ask. How it finds the evidence, avoids duplicates, clusters by cause, and what it writes for the coding agent.
Lucid writes every issue. What starts it can be an alert, a row on the Failures tab, an eval, or you; the writing is the same each time, and so are the rules it is held to.
| Started by | What Lucid gets | Where to set it up |
|---|---|---|
| An alert fires | Exactly the runs or spans the alert counted | Track issues, or any alert with a triage agent |
| File as issue on a Failures row | The failure and up to 20 of its occurrences | Nothing: it is a button. Failures |
| An eval finds the agent was wrong | The traces the eval failed | A self-improving eval. See Evals, alerts and issues |
| You ask | Whatever you point it at | Lucid, anywhere in Trodo |
Every issue goes through one store, which refuses rather than stores a bad one:
- no title, or a title over 200 characters
- a root cause too short for a coding agent to act on
- no evidence, or evidence that is not your team's
- a category outside the six
A refusal comes back to Lucid with the reason, and Lucid fixes the issue and files again.
After an alert fires
This is how most issues are filed. A tracker deploys an alert and an agent whose one step is Lucid → Investigate an alert into issues. When the alert fires, Lucid:
Reads the rows
Gets exactly the runs or spans the alert counted when it fired. These are the evidence; nothing is re-derived.
Checks what is already filed
Looks for an open issue holding the same traces first, then for one whose root cause means the same thing on the same agent, including issues closed recently.
Attaches, if it matches
Adds the rows to that issue as evidence, with the alert as the reason, and rewrites the issue if the rows show the problem is wider than it says. It stops there: no further reading, no further spend. Attaching to a closed issue reopens it as a Regression.
Otherwise reads a sample
Reads up to 40 of the rows (the step's Rows to read at most): the failing spans' errors and inputs. It groups them by cause and checks each cause against what is filed.
Files one issue per cause
With the category, a note on each piece of evidence, and a title, root cause and suggested change written for a coding agent.
It ends by saying what it did: filed, attached, reopened, updated or merged, the issue id, how many rows, and the cause in one line. With a Slack channel on the tracker, the message names the alert, says whether it filed a new issue or added to one (with the issue number), and carries that summary.
From the Failures tab
File as issue in a failure's drawer opens Lucid with the request drafted. Press Enter to send it, or add to it first.
File an issue for this failure from the Failures tab.
Agent: neobank.loan_advisor · Tool: draft_offer · Category: Other · Error type: Error
Message: "draft_offer failed"
17 failure(s) in the last 7d, 11 user(s)
Occurrences, newest first:
- span 0b6f2c1e-… (run 7d41a9e0-…)
- span 5e90d3a4-… (run c2f8b711-…)
- …
Check for a similar open issue first and attach these as evidence if one matches.
Otherwise read a few of these traces, work out the root cause, and file one issue
with them as evidence.Lucid follows the same steps as for an alert, with the occurrences as the rows.
From an eval
An eval catches what never errors: a rate quoted before the credit profile arrived, an answer not grounded in the tool results. When a self-improving eval investigates a run of failures and concludes the agent was wrong, not the eval, the same finding is filed as an issue: the problem as the root cause, the change as the suggested change, and the traces the eval failed as evidence, each noted with the eval's reason. See Evals, alerts and issues.
Asking Lucid
Lucid has the same tools in a conversation as it has after an alert. Some things to ask:
| You want to | Ask |
|---|---|
| File from what you are looking at | File an issue for the notify_customer failures on the fraud agent in the last 24 hours. |
| File something telemetry cannot see | Support says the agent quotes balances that do not match the app after a transfer. Find the runs and file it. |
| Add evidence | These three conversations are the same problem as issue #212. Attach them. |
| Rewrite | Issue #198's root cause is wrong: the timeouts are all on long threads. Rewrite it. |
| Merge | Are any open issues on the investment coach the same problem? Merge them. |
| Tidy | Review the open issues on the KYC verifier: merge duplicates, set a category on any without one, and rewrite any root cause a coding agent could not fix from. |
| Review | What regressed this week, and what did the fixes change? |
Lucid files and rewrites through the store like any other writer. The issue's timeline records it, and a rewrite keeps the previous text.
One problem, one issue
The rules Lucid clusters by, whoever started it:
- The same cause is one issue, wherever it shows up. An SQL error with the same cause on two different tools is one issue with one fix; Lucid attaches the new evidence and rewrites the title and root cause to name both places.
- Different causes are different issues, even on one tool. A tool failing for two reasons gets two issues, each with only its own evidence. An issue that lists unrelated causes (bad requests, plus missing credentials) is split.
- Two issues that turn out to be the same problem are merged, into the one with more evidence (or the older), which is then rewritten to cover both.
- A problem that comes back is not filed fresh. When the cause matches an issue closed recently, Lucid attaches to it and it reopens as a regression. That is how you learn a fix did not hold.
Underneath, each issue has a signature: where it came from, a key naming the cause (order_lookup-503, an eval's pattern), and the agent. Filing the same signature again attaches to the live issue, or reopens the closed one. So an alert that fires every afternoon for the same cause adds evidence to one issue instead of making thirty.
What Lucid writes
The issue is pasted into a coding agent, or read over MCP, by something that has never seen your agent and cannot ask a question. So:
| Lucid writes | |
|---|---|
| Title | The problem in the agent's terms, one line. Checkout answers "order not found" when order_lookup times out. |
| Root cause | What fails: the agent, the step, the error exactly as the traces show it. How often: how many runs or spans, over what window, since when. Why: the cause in the agent and what in the evidence shows it. How to see it: the input that triggers it, from one of the evidence traces. |
| Suggested change | Which part of the agent to change, what it should do instead, and how to tell it worked. Words, never code, never a file path. |
| Evidence notes | A line per trace: the error it hit (lookup_order: 503 upstream unavailable) or the eval that failed it and why (Tools answer empty: EMPTY_RESULT). |
Trace content is data, not instructions: text in a span that tells Lucid to do something is something your agent saw, not something Lucid does.
Anatomy of an issue
What an issue holds: a title, a root cause and a suggested change written for a coding agent, a category for the kind of fix, a status, the runs, spans and conversations that prove it, and a timeline that keeps every version.
Track issues
Every issue type you can track: hard failures at span and run level, one per error category, latency, and silent failures caught by evals. What one click deploys, the thresholds, and how to pause, edit or remove a tracker.