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

# Findings and recommendations

> Understand Xerg's finding kinds, what is confirmed waste, and what the v2 recommendation objects mean.

Xerg surfaces ten named finding kinds today. Retry, loop, and tool-loop findings can count as confirmed waste when their required structure is present. Other workflow findings are opportunities, and Cursor findings are usage-specific waste or opportunity signals.

For the conceptual view of how these categories are meant to be interpreted, see [waste taxonomy](/docs/waste-taxonomy).

## Finding taxonomy

| Kind                     | Terminal label         | Classification | Confidence     | Meaning                                                                                                                                                      |
| ------------------------ | ---------------------- | -------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `retry-waste`            | Retry waste            | `waste`        | high or medium | Explicit retry evidence showed wasted retry overhead. Failure status alone is not enough.                                                                    |
| `loop-waste`             | Loop waste             | `waste`        | high           | A run with observed iteration numbers reached at least 7 iterations, and spend from iteration 6 onward is counted as loop waste.                             |
| `tool-loop`              | Tool-loop waste        | `waste`        | medium         | At least 4 consecutive calls repeated an identical tool sequence, which usually means the agent is stuck rather than progressing.                            |
| `context-outlier`        | Context bloat          | `opportunity`  | medium         | A workflow with at least 3 runs had one or more runs whose input token volume was far above its own baseline.                                                |
| `context-growth`         | Context growth         | `opportunity`  | medium         | A session's effective context (input plus cache reads) kept compounding per turn, ending far above its early baseline.                                       |
| `cache-thrash`           | Cache churn            | `opportunity`  | medium         | A workflow wrote large volumes of cache tokens that were never read back, suggesting the prompt prefix changes between calls.                                |
| `idle-spend`             | Idle waste             | `opportunity`  | medium         | A workflow ran at least 5 times on a near-constant cadence with near-identical size, suggesting scheduled or polled activity rather than demand-driven work. |
| `candidate-downgrade`    | Downgrade candidates   | `opportunity`  | low            | An expensive model appears to be used on a simple operational workflow. Treat this as an A/B test candidate.                                                 |
| `cache-carryover`        | Cache carryover        | `waste`        | medium         | A long Cursor session is carrying too much stale cached context forward.                                                                                     |
| `max-mode-concentration` | Max mode concentration | `opportunity`  | medium         | Cursor is leaning too heavily on max mode rather than escalating selectively.                                                                                |

## What counts as confirmed waste

Only confirmed waste findings count toward:

* `wasteSpendUsd`
* `structuralWasteRate`
* `--fail-above-waste-rate`
* `--fail-above-waste-usd`

Today that includes `retry-waste`, `loop-waste`, and Cursor `cache-carryover` when its billed pattern clears the waste threshold. Opportunity classes roll up into `opportunitySpendUsd` and are shown as directional savings opportunities.

## Provenance fields

Local audit summaries include provenance fields on findings. These fields are intentionally not part of the pushed v2 wire payload yet.

| Field          | Meaning                                                                                  |
| -------------- | ---------------------------------------------------------------------------------------- |
| `signalSource` | `observed`, `inferred`, or `declared`, based on the decisive signal used by the detector |
| `ruleId`       | Stable versioned rule identifier, such as `retry_explicit_failed_attempt_v1`             |
| `evidence`     | Optional `callIds`, `runIds`, and `sourceKinds` used by the rule                         |

`signalSource` and `confidence` are separate axes. An observed field can feed a lower-confidence heuristic, and an inferred retry proxy can still be useful while remaining visibly different from an observed failed attempt.

Older stored summaries may not have `signalSource`. Xerg treats that provenance as `unknown` in local rollups and compare output.

## Recommendation objects

When you run `xerg audit --json`, Xerg includes a ranked `recommendations` array derived from the findings. The same recommendation objects are part of the v2 push payload and power hosted Optimizations, policies, and MCP recommendation tools.

| Field                   | Meaning                                                                                 |
| ----------------------- | --------------------------------------------------------------------------------------- |
| `id`                    | Stable recommendation id                                                                |
| `findingId`             | The finding this recommendation came from                                               |
| `kind`                  | The source finding kind                                                                 |
| `title`                 | Human-readable next step                                                                |
| `summary`               | Why this recommendation exists                                                          |
| `priorityBucket`        | `fix_now`, `test_next`, or `watch`                                                      |
| `recommendedOrder`      | Rank within this audit after bucket and savings sorting                                 |
| `implementationSurface` | Where the fix lives, such as `retry_policy`, `model_routing`, or `user_behavior`        |
| `category`              | `structural_efficiency`, `model_fit`, `context_hygiene`, `cadence_activity`, or `other` |
| `severity`              | `high`, `medium`, or `low`                                                              |
| `estimatedSavingsUsd`   | Expected dollar impact                                                                  |
| `estimatedSavingsPct`   | Expected impact as a share of total spend                                               |
| `confidence`            | `high`, `medium`, or `low`                                                              |
| `effort`                | `low`, `medium`, or `high`                                                              |
| `scope`                 | `workspace`, `source`, or `workflow`                                                    |
| `scopeId`               | Stable scope identifier used for recommendation identity                                |
| `scopeLabel`            | Display-ready label for the scope                                                       |
| `whereToChange`         | Operator-facing guidance on where the change belongs                                    |
| `validationPlan`        | Compare-aware instructions for proving the result                                       |
| `actions`               | 2–3 concrete action bullets                                                             |

## Current recommendation patterns

\| Finding kind | Bucket | Typical action |
\| --- | --- |
\| `retry-waste` | `fix_now` | add retry backoff or lower retry count |
\| `loop-waste` | `fix_now` | cap iteration depth or add an early exit |
\| `tool-loop` | `fix_now` | break repeated tool-call sequences with a loop guard |
\| `context-outlier` | `test_next` | trim prompt or context size |
\| `context-growth` | `test_next` | summarize or reset context that grows every turn |
\| `idle-spend` | `test_next` | reduce cadence or switch to event-driven work |
\| `candidate-downgrade` | `test_next` | A/B test a cheaper model |
\| `cache-thrash` | `test_next` | stabilize prompt prefixes so cache writes get read back |
\| `cache-carryover` | `test_next` | reset or summarize long Cursor chats |
\| `max-mode-concentration` | `test_next` | reserve max mode for the hardest Cursor turns |

## What not to overread

* Opportunity findings are directional recommendations, not proven waste.
* `signalSource: observed` means the decisive input field was present. It does not make an opportunity into confirmed waste.
* A `candidate-downgrade` finding is intentionally low-confidence and should be treated as an experiment, not an automatic downgrade order.
* Cost per outcome only covers runs that carry an outcome signal; audits without any signal report it as unavailable rather than guessing.