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.
An issue is one problem in one agent. It says what fails and why, what to change, and which traces show it, written so a coding agent that has never seen your agent can fix it from the issue alone.
The fields
| Field | |
|---|---|
| Title | The problem in the agent's terms, one line. Same-day wires initiated after the cut-off. |
| Agent | The agent it belongs to. An issue never spans two agents. |
| Category | The kind of fix it needs. See Categories. |
| Status | Open, Regression, Closed or Merged. See Statuses. |
| Root cause | What fails, how often, why, and how to see it. |
| Suggested change | The change to make, in words. Never code: that is the coding agent's job. |
| Evidence | The runs, spans and conversations that show the problem. |
| First seen, Last seen | The earliest and latest evidence. |
| Version | 1 when filed, one more each time the title, root cause or suggested change is rewritten. Shown as v2, v3 in the header. |
An issue cannot exist without evidence, and a root cause too short to act on is refused when it is filed. Lucid writes root causes of at least a few sentences; see Writing an issue a coding agent can fix.
Categories
The category is where the fix lives, not what the symptom looked like. A timeout can be infrastructure (the provider is slow) or model (a long context makes every call slower) or code (the agent never retries).
| Category | The fix is in | For example |
|---|---|---|
| Code | The agent's own code | A parser that throws on an empty list; a tool call built with the wrong argument; an unhandled exception. |
| Prompt | Its instructions | It answers outside its scope, ignores a tool result, or quotes a rate before the credit profile arrives. |
| Tool | A tool or external API, or how it is called | A search tool returning nothing for valid queries; a failed call that is never retried. |
| Infrastructure | Timeouts, rate limits, capacity, credentials, config, deploys | 429s from the model provider; a 503 from a service under load; an expired key. |
| Data | Retrieval, or data that is missing, stale or wrong | The index has no passages for EU ID cards; a balance read from a cache that lags the ledger. |
| Model | The model itself, given the right context | It invents a figure the tools never returned, or is cut off at the token limit. |
These are not the Failures categories. A failure's category (Timeout, Auth, Code error) says what the error was; an issue's says what kind of change fixes it. When the evidence does not settle it, Lucid picks the most likely and says why in the root cause.
Statuses
| Status | Means | Gets there when |
|---|---|---|
| Open | A live problem. | It is filed, or someone clicks Reopen. |
| Regression | It was closed, and it came back. | New evidence lands on a closed issue: an alert fires and Lucid attaches to it, or an eval files the same finding again. |
| Closed | Fixed, or not worth fixing. | Someone clicks Mark closed, or a coding agent closes it over MCP. |
| Merged | The same problem as another issue. | Someone merges it. Its evidence moves to the other issue and it points there. |
- OpenFiled with evidence.
- ClosedYou ship the fix and mark it closed.
- RegressionThe same cause shows up again; the issue reopens itself.
- ClosedFixed properly this time.
A regression is the most useful thing the status tells you: the fix did not hold. It is why a closed issue is never deleted and a returning problem is never filed fresh. See Regressions.
A merged issue leaves the list, cannot be edited and cannot take new evidence; opening one shows Merged into #id with a link.
Evidence
Evidence is what the issue is made of: the traces that show this cause and nothing else.
| Kind | Used when |
|---|---|
| Span | One step shows the problem: the failing tool call, the empty retrieval, the model call that timed out. The most specific kind, and the one Lucid prefers. |
| Run | The whole run shows it: it failed with no step to blame, or the problem is in how the steps fit together. |
| Conversation | The problem is across turns: the user had to repeat themselves, or left after a failed answer. |
The Evidence tab lists them newest first. What it shows is filled from the trace itself:
- the step and its error:
notify_customer · Error: notify_customer failed - any eval that failed on that trace, as a chip that opens the eval result:
Loan advice triage failed · RATE_OUT_OF_POLICY - the note written when it was attached, when there is nothing else to say
Click a row to open its trace in the drawer (a conversation opens in Conversations). Traces age out with your retention; evidence whose trace is gone stays on the issue and says Trace no longer kept.
Timeline
The Timeline tab is everything that happened to the issue, newest first, with who did it: Lucid, A person, Coding agent or Trodo.
| Entry | |
|---|---|
| Filed with 20 pieces of evidence | When and why it was filed; From an eval links the eval when one filed it. |
| Linked 6 more pieces of evidence | New evidence, with the reason (the alert fired again overnight) and the traces as chips you can open. |
| Version 2: rewrote the title, root cause, suggested change | A rewrite. Show the previous version shows the text it replaced. |
| Closed · Reopened · Came back (regression) | Status changes. |
| Merged into #184 · Merged #191 into this, 8 pieces of evidence moved | Merges, with the reason. |
Fix started · Fix branch trodo/heal-wire-cutoff | A coding agent working on it. |
| A note | Free text, such as Shipped in agents v2.14; no late same-day wires rejected since. |
Nothing is overwritten. An issue rewritten three times has its three earlier texts on the timeline.
The Issues tab
The Issues tab lists them: the status as a dot beside the title, then the category, the amount of evidence, a 30-day trend of new evidence and when it was last seen. Open and regressed issues come first, then by last seen.
| Control | |
|---|---|
| Search | Title or root cause. |
| Status | Open and Regression by default; add Closed to see fixed ones. |
| Category | Any of the six, or Not set. |
| Agent | One or more agents. |
| Track issues | Deploy trackers. See Track issues. |
Click a row to open the issue in a drawer; the arrows step through the list. A link ending in ?issue=<id> opens that issue directly: that is what the Signals tab on a trace and Lucid's answers link to.
The drawer's actions: Fix (hand it to a coding agent), Copy as prompt, Merge into…, and Mark closed or Reopen. See Fixing an issue.
Examples
A catalogue from a set of banking agents, showing the range:
| Issue | Agent | Category | Filed from | Status |
|---|---|---|---|---|
| Customer never told after a card freeze: notify_customer fails and is not retried | fraud_detection | Tool | Failed-steps alert | Open, fix branch pushed |
| kyc-rulebook search unavailable, so documents are checked without the rulebook | kyc_verifier | Infrastructure | Retrieval-failures alert | Regression |
| Model calls time out on long support threads | customer_support | Model | Failed-steps alert | Open, v2 |
| Rate quoted without pulling the live credit profile | loan_advisor | Prompt | Eval: Loan advice triage | Open |
| Routing number validated but the beneficiary bank shown is wrong | transfer_router | Code | Eval: Transfer is routed correctly | Open |
| Rulebook search returns nothing usable for non-UK documents | kyc_verifier | Data | Eval: Retrieval returned usable context | Open |
| Same-day wires initiated after the cut-off | transfer_router | Code | Failed-steps alert | Closed |
| Balance quoted from a stale cache after a recent transfer | customer_support | Data | A person, through Lucid | Closed |
| Benchmark comparison uses a stale quote snapshot when fetch_quotes fails | investment_coach | Tool | Failed-steps alert | Open, one issue merged in |
A root cause, rewritten
Model calls time out on support conversations was filed from a failed-steps alert with a thin first version. When the alert fired again, Lucid matched the timeouts against conversation length and rewrote it as version 2:
Root cause. chat.completions calls from the support agent time out (TimeoutError, "model timed out") on conversations with long histories. The whole thread goes into every call, so latency grows with each turn until the provider's timeout cuts it off. The customer gets no answer and asks again, which makes the next call longer still.
Suggested change. Summarise turns older than the last ten before calling the model, and on a timeout retry once with the trimmed context rather than failing the turn.
Reason for the rewrite: almost all of the timeouts are past the tenth turn.
The first version is still on the timeline under Show the previous version.
Failures
The Failures tab groups every failed span and run by agent, tool, error type and category. What counts as a failure, the ten categories, the charts, the table, and turning a row into an issue or an alert.
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.