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

# Waste taxonomy

> Understand Xerg's finding kinds, confidence levels, and the difference between confirmed waste and directional opportunities.

Xerg classifies spend into two groups:

* confirmed waste
* savings opportunities

This distinction is important because only confirmed waste contributes to `wasteSpendUsd`, `structuralWasteRate`, and CI threshold checks.

## The current finding kinds

### Retry waste

Classification: `waste`\
Confidence: usually `high` when explicit failed attempts are observed, `medium` when a later retry attempt is used as a proxy

Xerg counts retry waste from explicit retry evidence when the source records it: the strongest case is a failed or aborted attempt followed by a later explicit retry attempt in the same run. If only the later retry attempt is visible, Xerg may count that later attempt as inferred retry overhead with lower confidence.

Session transcripts (OpenClaw sessions, Claude Code) carry no explicit attempt fields, so Xerg uses transcript inference there: an errored call followed by a same-model call within ten minutes counts the failed call's spend as inferred retry overhead.

Typical fix:

* add exponential backoff
* reduce retry count
* avoid retrying known non-recoverable failures

### Context bloat

Classification: `opportunity`\
Confidence: `medium`

For workflows with at least three runs, Xerg looks for runs whose input token volume is far above that workflow's own baseline. This is a directional context-trimming signal, not proven waste.

Typical fix:

* trim prompt scaffolding
* send less repeated context
* split broad tasks into smaller scoped calls

### Loop waste

Classification: `waste`\
Confidence: `high`

When a source records iteration numbers and a run reaches at least seven iterations, Xerg treats spend from iteration six onward as loop waste. If iteration structure is missing, Xerg suppresses loop waste rather than inferring it from a flat log.

Typical fix:

* add an iteration cap
* add an early exit condition
* tighten workflow guardrails

### Tool-loop waste

Classification: `waste`\
Confidence: `medium` (inferred)

When a source exposes tool identity, four or more consecutive calls invoking an identical tool sequence indicate an agent stuck re-running the same operation. Spend beyond the second repetition is counted as likely loop waste.

Typical fix:

* detect repeated identical tool calls and stop after a few repeats
* add a progress check between iterations
* surface the loop to the user instead of retrying silently

### Context growth

Classification: `opportunity`\
Confidence: `medium`

Within a single session, when effective context (input plus cache reads) at least doubles from its early baseline and ends above 50k tokens, every later call is paying for the accumulated context. Earlier compaction or trimming compounds savings.

Typical fix:

* compact the session before context reaches the flagged size
* trim stale tool results from history
* split long sessions into fresh ones

### Cache churn

Classification: `opportunity`\
Confidence: `medium`

When a workflow writes far more tokens to prompt cache than it ever reads back, the cache-write premium is not paying for itself. This usually means the prompt prefix changes between calls and invalidates the cache.

Typical fix:

* keep the system prompt and early context byte-stable
* move volatile content out of the prompt prefix
* verify cache hits with provider usage reports

### Downgrade candidates

Classification: `opportunity`\
Confidence: `low`

Xerg flags expensive models on workflows that look operationally simple, such as heartbeat, triage, summary, tagging, or monitoring style tasks. This is intentionally an A/B test candidate rather than a claim of proven waste.

Typical fix:

* test a cheaper model on the same workflow
* compare quality and cost before changing defaults

### Idle waste

Classification: `opportunity`\
Confidence: `medium`

Xerg looks for cadence evidence: five or more runs firing at a near-constant interval with near-identical size, whatever the workflow is named. The spend may still be justified, but the cadence and model tier are worth reviewing.

Typical fix:

* reduce cadence
* move to event-driven triggering
* use a cheaper model for routine checks

### Cache carryover

Classification: `waste`\
Confidence: `medium`

For Cursor usage audits, Xerg flags extreme long-session cache carryover as waste when too much stale cached context is being dragged through the session and the billed pattern clears the waste threshold.

Typical fix:

* summarize long chats into a short recall note
* start a fresh chat
* carry forward only the facts that still matter

### Max mode concentration

Classification: `opportunity`\
Confidence: `medium`

For Cursor usage audits, Xerg flags workflows or usage patterns that lean too heavily on max mode instead of escalating selectively.

Typical fix:

* default to standard mode
* escalate only when standard mode fails
* review auto-escalation habits

## Confidence levels

| Level    | Meaning                                                              |
| -------- | -------------------------------------------------------------------- |
| `high`   | Strong waste signal that is usually safe to act on immediately       |
| `medium` | Directional signal that should be investigated                       |
| `low`    | Experiment candidate rather than a direct recommendation to roll out |

## Provenance

Findings also carry local provenance fields in the core summary:

| Field          | Meaning                                                               |
| -------------- | --------------------------------------------------------------------- |
| `signalSource` | Whether the decisive signal was `observed`, `inferred`, or `declared` |
| `ruleId`       | Versioned detector rule that emitted the finding                      |
| `evidence`     | Optional call, run, and source-kind references used by the rule       |

Older summaries can lack `signalSource`. Xerg treats those findings as `unknown` in local rollups instead of assuming they were observed.

## Why this matters in the product

* `retry-waste`, `loop-waste`, `tool-loop`, and qualifying Cursor `cache-carryover` roll up into confirmed structural waste when their required structure is present
* `context-outlier`, `context-growth`, `idle-spend`, `candidate-downgrade`, `cache-thrash`, and Cursor `max-mode-concentration` roll up into opportunity impact
* the Action queue and hosted Optimizations backlog may prioritize an opportunity even when it is not confirmed waste

For the recommendation object shape returned in JSON mode, see [findings and recommendations](/docs/findings-and-recommendations).
