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

# Deviations

> A deviation is a recurring type of misbehavior Glassray finds across your traces - with a review lifecycle and a proposed code-level fix.

A **deviation** is a recurring *type* of misbehavior - for example "retrieval returned no sources", "overstated a claim the sources don't support", or "skipped a required verification step". Glassray finds concrete examples across many traces (instances) and clusters them into a deviation type, so you review a pattern once rather than triaging the same problem trace by trace.

Each deviation is found against your **spec** - the generated description of what your agents are supposed to do - and is linked to the [flow](/flows) it affects.

## Lifecycle

A deviation moves through a Linear-style lifecycle. Every transition is recorded with a short reason, so nothing changes status silently.

| Status        | What it means                                                                                                                                                                                                   | Who sets it    |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
| **Suspected** | A fresh candidate Glassray is still gathering examples for - not yet recurring (or precise) enough to be confirmed work.                                                                                        | Glassray       |
| **Confirmed** | Confirmed work: it recurs (around 3–5 examples) and the examples check out, or it's critical. Glassray promotes a Suspected deviation automatically once it clears that bar - and you can confirm one yourself. | Glassray / you |
| **Done**      | Resolved - a fix landed and Glassray matched the commit or pull request, or you marked it done.                                                                                                                 | Glassray / you |
| **Cancelled** | Set aside - judged by-design or not a bug, or folded into another deviation as a duplicate.                                                                                                                     | You / Glassray |

<Note>
  If you've connected [Slack](/slack), Glassray posts each deviation to your channel - by default only once a deviation is **Confirmed**, so you're not pinged for candidates that are still being investigated. You can lower that threshold to be notified as soon as a deviation is **Suspected**, so you can confirm or dismiss it right from the card.
</Note>

## Finding more examples

While a deviation is **Suspected**, Glassray is still building the case - scanning your recent trace history for more instances so you can see how often it really happens. Once it recurs in enough examples, Glassray promotes it to **Confirmed** automatically; until then it stays **Suspected**. You can also kick off this search yourself from the deviation.

## What happens when you confirm

Confirming a deviation - promoting it to **Confirmed**, yourself or automatically - generates a fix:

<Card title="A proposed fix" icon="code-pull-request">
  Glassray generates a code-level fix suggestion - a prompt or logic change - that you review and apply like any pull request. If Slack is connected, the deviation's thread gets a "generating a fix" update.
</Card>

<Warning>
  The fix is a **proposed diff you review** - Glassray does not auto-merge it. You stay in control: review the suggestion, attach it to the failing trace as evidence, and ship it through your normal review process.
</Warning>

## Where deviations come from

Most deviations come from Glassray's own scan against your spec. But you can also surface them from outside the loop:

<CardGroup cols={2}>
  <Card title="From feedback" icon="thumbs-down" href="/signal">
    A negative signal pinned to a trace is actioned - Glassray sorts that trace into a flow and creates or appends to a deviation.
  </Card>

  <Card title="From Slack" icon="slack" href="/slack">
    Describe a misbehavior to the Glassray bot and it can log a deviation from the conversation and scan for more instances.
  </Card>
</CardGroup>

<Tip>
  You can review, confirm, and inspect deviations in the dashboard, or programmatically over the [MCP server](/mcp-server) with `list_deviations`, `get_deviation`, and `update_deviation_status`.
</Tip>