> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zespan.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Issues — recurring failures grouped automatically

> Zespan clusters repeated failed and degraded traces into a single recurring Issue, using the same deterministic verdict system shown on every trace, so you stop re-discovering the same problem one trace at a time.

The Issues page turns N separate failing traces that are really the same underlying problem into one row: a recurring **Issue** with an occurrence count, a first/last-seen timestamp, and a link to a real sample trace.

<Note>
  Issue clustering runs automatically in the background — there's nothing to configure. It requires the **Pro** plan or higher.
</Note>

## How clustering works

A background worker re-runs the same deterministic verdict classifier used on every trace detail page (the one that decides whether a trace is `healthy`, `degraded`, or `failed`) against recent candidate traces, then groups matches by `(verdict level, primary operation, error code)`. Traces that land in the same group become occurrences of one Issue.

Because it's the same classifier your trace detail page already shows you — not a second, fuzzier system guessing from raw scores — an Issue's grouping key means exactly what it says: these traces failed the same way, for the same reason, on the same operation.

## The Issues list

Each row shows:

| Field         | Description                                                                                                |
| ------------- | ---------------------------------------------------------------------------------------------------------- |
| Verdict level | `degraded` or `failed`                                                                                     |
| Operation     | The operation type this issue recurs on                                                                    |
| Error code    | The shared error code, if any                                                                              |
| Occurrences   | How many traces have matched this issue                                                                    |
| Last seen     | The clustering window this issue spans                                                                     |
| Actions       | **View details**, **View sample trace**, **View related prompt** (if applicable), **Resolve**, **Dismiss** |

Click **View details** to open the [Issue detail page](#issue-detail-page) for the full sample-trace list and the remediation suggestion feature. **View sample trace** jumps straight to one real occurrence in the normal flame graph view, so you can investigate the actual failure without leaving the list.

## Resolved vs. dismissed

Both actions remove an issue from the open Issues list — the difference is what they communicate, the same distinction [Sentry-style issue trackers](https://docs.sentry.io/product/issues/states-triage/) draw between the two:

| Action      | Meaning                                                                               |
| ----------- | ------------------------------------------------------------------------------------- |
| **Resolve** | "I fixed the underlying problem."                                                     |
| **Dismiss** | "Stop showing me this recurring pattern" — regardless of whether it's actually fixed. |

Neither is permanent: if the aggregator detects a fresh occurrence of the same cluster (same verdict level, operation, and error code) after an issue was resolved or dismissed, the issue reopens and reappears in the open Issues list. Resolving an issue you haven't actually fixed just means it comes back sooner.

<Tip>
  An issue with a rapidly climbing occurrence count is usually a better place to start than sorting the Traces log by timestamp — it's already told you this isn't a one-off.
</Tip>

## Issue detail page

Clicking into an Issue (`/{orgSlug}/{projectId}/issues/{issueId}`) shows:

* The verdict level, current status, occurrence count, and first/last-seen timestamps
* A link to the associated prompt, if this issue's traces share one
* **Mark resolved** / **Dismiss** actions (same semantics as the list — see [above](#resolved-vs-dismissed))
* A **Sample traces** table — up to 10 representative traces from the cluster, each linking out to its full trace detail view
* The **Generate suggestion** remediation feature, described below

### Generate suggestion (remediation)

<Note>
  Requires the **Pro** plan or higher, same as the rest of the Issues feature.
</Note>

Click **Generate suggestion** on the Issue detail page to have Zespan investigate the pattern for you: it runs the same [root cause analysis](/dashboard/traces#root-cause) used on individual traces against up to 5 representative sample traces from the cluster, then hands those findings to [ZespanPilot](/dashboard/zespanpilot) to write a short markdown suggestion — the likely underlying cause and one concrete next step, reasoned over the *recurring pattern* rather than a single occurrence.

<Warning>
  This is a **markdown suggestion only**. Generating it never opens a pull request, proposes a code diff, or touches any source repository — Zespan has no repo-connection integration today. Treat it as a starting point for your own investigation, not an automated fix.
</Warning>

The suggestion is cached per issue, so regenerating it (e.g. after revisiting the page) is instant and doesn't re-run the analysis or incur additional cost. If none of the sampled traces can be analyzed — for example, they've aged out of trace retention — you'll see an error instead of a suggestion; try again once the issue has recurred and produced fresher samples.

### Automatic remediation suggestions

<Note>
  Requires the **Pro** plan or higher, same as manual **Generate suggestion**. Free and Solo plan Issues are not auto-analyzed, but you can still generate a suggestion yourself at any time using the manual button above.
</Note>

Once an Issue has recurred **three or more times**, Zespan generates a remediation suggestion for it on its own — you don't have to ask. The suggestion appears on the Issue detail page labelled with the time it was generated, so opening a recurring failure usually means reading the analysis rather than requesting it.

The analysis reasons **across** the Issue's sample traces rather than about one of them, and says which situation it found:

| Finding               | What it means                                                                                                                                                        |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| One shared root cause | Every sampled occurrence points at the same underlying failure. The suggestion describes it once and gives one next step.                                            |
| Several failure modes | The occurrences are different problems that happen to share the same verdict, operation, and error code. The suggestion groups them and gives a next step per group. |
| Single occurrence     | Only one sample could be analysed (the others aged out of retention, or carry no error span). The finding is marked provisional.                                     |

<Note>
  Suggestions are text only. Zespan never opens a pull request, edits your prompts, or changes your configuration as part of generating one — you decide what to act on.
</Note>

You can still press **Generate suggestion** yourself on an Issue that hasn't reached three occurrences, or ask ZespanPilot directly: "investigate the rate limit issue on chat.completions.create."

## Issues feed regression tests

Once an issue has recurred 3 or more times, it's automatically captured as a test case in a **Production Failures** dataset — turning your own incident history into a regression suite your CI can replay against a candidate change. See [Regression testing from production failures](/dashboard/datasets#regression-testing-from-production-failures).

## Next steps

* [Traces](/dashboard/traces#root-cause) — the underlying root-cause analysis that powers remediation suggestions
* [ZespanPilot](/dashboard/zespanpilot) — the AI copilot that writes remediation suggestions
* [Guardrails](/dashboard/guardrails) — if an issue's error code traces back to a guardrail violation, promote that violation into a permanent rule
* [Datasets](/dashboard/datasets) — replay recurring issues as regression tests
* [Incidents](/dashboard/incidents) — for anomaly-driven correlation across metrics, rather than verdict-based trace clustering