Skip to main content
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 a rule - one expected behaviour of the flow it affects - and, more broadly, against your spec, the generated description of what your agents are supposed to do.

​
Lifecycle

A deviation moves through a Linear-style lifecycle. Every transition is recorded with a short reason, so nothing changes status silently.
If you’ve connected 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.

​
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.

​
Short IDs

Every deviation has a short ID, like DEV-142, shown next to its title and on each card in the list. In Slack and Ask Glassray you can just say “DEV-142” and Glassray looks it up. Over the MCP server, get_deviation, link_pull_request and unlink_pull_request accept it; the other deviation tools take the deviation’s dev_… id, which get_deviation returns. IDs are unique across your organization and never reused.

​
The fix

Once a deviation is Confirmed, you can ask Glassray for a fix: click Propose fix on the deviation page, or Generate fix on its Slack card. Confirming alone doesn’t generate one.

A fix your coding agent can apply

The fix is a markdown instruction document written for your coding agent (or you): what goes wrong, the change to make - usually a prompt, tool-description or logic change - what to verify, and acceptance criteria. Copy it into Claude Code, Cursor or any coding agent, which makes the change in your repo.
Glassray never edits your repository or opens pull requests itself. The fix is guidance: you (or your coding agent) make the change and ship it through your normal review process.
Every fix ends with a Tracking section that names the deviation (DEV-142) and the branch to create - for example glassray-dev-142-client-quote-isnt-the-clients-words. You can also grab the branch name from the Copy branch name button next to the deviation’s title.

​
Pull requests

When a pull request’s branch name, title or description contains glassray-dev-142, Glassray links it to DEV-142 automatically and posts one comment on the PR pointing back to the deviation. The deviation page’s Pull requests panel lists every linked PR with its live state - open, draft, merged or closed - and you can attach or remove one by hand. See GitHub.
Linking or merging a PR doesn’t change the deviation’s status. Mark it Done yourself once you’re happy the fix holds.

​
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:

From feedback

A negative signal pinned to a trace is actioned - Glassray sorts that trace into a flow and creates or appends to a deviation.

From Slack

Describe a misbehavior to the Glassray bot and it can log a deviation from the conversation and scan for more instances.
You can review, confirm, and inspect deviations in the dashboard, or programmatically over the MCP server with list_deviations, get_deviation, update_deviation_status, and link_pull_request.