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

> ## Agent Instructions
> For API and SDK launches, integration testing, and ongoing coding-agent checks, start with Gauge Agents:
> - [Gauge Agents overview](https://docs.withgauge.com/agents/index.md)
> - [Gauge Agents quickstart](https://docs.withgauge.com/agents/quickstart.md)
> - [Create and inspect an eval](https://docs.withgauge.com/agents/guides/create-an-eval-and-run-an-experiment.md)
> - [Agent Experience: diagnose integration failures](https://docs.withgauge.com/agents/concepts/agent-experience.md)
> - [Agent Preference: measure product selection](https://docs.withgauge.com/agents/concepts/agent-preference.md)
> - [GitHub PR checks](https://docs.withgauge.com/agents/guides/github-pr-checks.md)
> For AI search visibility and AEO, start with [Gauge Chat](https://docs.withgauge.com/introduction/welcome.md).

# Issues

> How Gauge groups the findings from many coding sessions into issues, and how to read them.

A **finding** is one problem or objection in one session. An **issue** is the same finding across many sessions. Gauge reads every analyzed session, records its findings, and groups them into issues for each of your products.

Issues show you what to fix first. Each issue counts the sessions it affects and links to the evidence in each one.

## Two kinds of issue

| Kind | Source | What it shows |
| - | - | - |
| Friction | [Agent Experience](https://docs.withgauge.com/agents/concepts/agent-experience.md) | A problem agents hit while they used your product. The list shows its impact. |
| Objection | [Agent Preference](https://docs.withgauge.com/agents/concepts/agent-preference.md) | A reason agents gave when they chose another product. The list shows where they went. |

The CLI and API call friction issues `friction` or `problems`, and objection issues `objection` or `reasons`.

## Where to find issues

Open **Agent Experience** or **Agent Preference** and select the **Issues** tab. Gauge shows one block for each of your products. Each block starts with a headline, such as "Agents ran into problems with Acme CLI in 11 of 31 sessions."

Each row in the block is one issue:

| Column | Meaning |
| - | - |
| Title | What the findings in the issue have in common. |
| Sessions | The number of sessions in the current filter with a finding in the issue. |
| Impact (friction) | The sessions for each effect: blocked, extra work, or recovered. |
| What the agent chose instead (objection) | The products agents chose instead, with the number of sessions for each. |

The page filters apply to every count. Change the date range, prompt, agent, model, or tags, and the counts change to match.

Click a row to open the issue details. The details show the description and each finding with its agent, model, and effect. Click a finding to open its run. Click **Open in Coding sessions** to see every session in the issue.

## How Gauge groups findings

Grouping is automatic. Gauge groups new findings a few minutes after each run is analyzed.

* Gauge groups only findings about your own products. Your brand catalog sets which products are yours.
* Friction caused by missing access, the run environment, or the agent itself is not grouped. These findings stay on the run page.
* A new issue needs at least two findings. A finding that matches no issue waits until a similar finding arrives.
* Optimization reruns and forked runs do not add findings to issues.
* When Gauge analyzes a run again, the new findings replace the old findings.

Some findings are not in an issue yet. `gauge issues list` shows how many.

## Issue status

Each issue is **Open**, **Fixed**, or **Muted**. Gauge reopens a fixed issue when a later run shows it again. You can rerun past sessions to check if an issue is gone. See [Manage issues](https://docs.withgauge.com/agents/guides/manage-issues.md).

## Fix an issue

Click **Optimize** on an issue to test a fix. Gauge edits copies of the docs, Skills, or CLI rules the agents used, and reruns the sessions behind the issue. See [How optimizations work](https://docs.withgauge.com/agents/guides/how-optimizations-work.md).

## Read issues from the CLI

```bash theme={null}
gauge issues list                     # open issues, most sessions first
gauge issues list --type friction     # or --type objection
gauge issues get <issue-id>           # the issue's findings and runs
gauge run insight <run-id>            # one run's findings and their issues
```

For a coding agent, run `gauge instructions issues`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.