Findings, signals, and recommendations

Xerg 0.21.0 exposes three active monetary finding kinds and seven neutral signal kinds. A finding requires the observations and exact cost correlation needed to calculate an avoidable amount. A signal reports a factual pattern only: it has no classification, avoidable-spend amount, recommendation, optimization record, or CI impact. Older pushed audits remain readable under their original detector method and are marked Legacy detection method. They do not recur into current optimization records.

​

Active monetary findings

affectedSpendUsd is the spend involved in the observed pattern. avoidableSpendUsd is the smaller detector-owned amount that recommendations, totals, and gates may use. The component-level claim ledger prevents two findings from claiming the same economic component: retry waste takes precedence over tool-loop waste for a model charge, while cache thrash may claim only a cache-premium component.

​

Neutral signals

These patterns can be useful audit leads, but none independently proves waste. In particular, high cache-read concentration can reflect discounted reuse, and Max Mode can be appropriate for complex work. For chain-backed deep-loop-activity, the content-free toolInputDistinctRatio compares distinct canonical (tool name, input digest) pairs with participating tool executions. A high ratio argues against an identical-input loop and is consistent with fan-out; it does not prove task success. A low ratio is a reason to inspect, not proof of waste or recoverability. The ratio appears only with complete fingerprint coverage. chainOccurrenceCount and fingerprintedToolExecutionCount provide its bounded context. Local reports add repeated tool-chain diagnostics for contiguous n-grams of two to five tool names that occur at least three times and involve at least seven unique executions. Their associated spend is explicitly non-additive and rendered as Associated spend — not classified as waste. Use xerg explain to inspect their digest-only evidence and limitations.

​

Detector coverage

Coverage is reported separately for all three findings and all seven signals. A detector is unavailable when its source lacks a required observation; Xerg never substitutes a timing, name, aggregate-ratio, or later-call proxy. Coverage includes bounded reason codes such as missing_request_correlation, missing_tool_fingerprint, missing_cache_identity, and not_supported_by_source. Only active findings count toward:

• wasteSpendUsd
• structuralWasteRate
• --fail-above-waste-rate
• --fail-above-waste-usd
• ranked recommendations and hosted Optimizations

Signals remain visible in terminal, JSON, MCP, API, dashboard, and generated reports without entering any of those totals or workflows. Human-readable reports show their ordered observed metrics, scope, observation confidence, and optional associated spend with an explicit non-waste warning. Per-detector coverage distinguishes “not observed” from “not assessed.”

​

Finding fields on Push v7

Push v7 signals use the separate payload introduced in v6, with kind-specific, content-free metrics, optional associatedSpendUsd, and optional associatedSpendBasis (observed-charge, catalog-estimate, or mixed). Xerg 0.27.0 additively includes optional scopeLabel when the source provides a human-readable workflow/run label; consumers fall back to scopeId, and earlier v7, v6, and stored v5 history remain valid without it. Current producers set the spend basis whenever associated spend is present; tolerant readers accept earlier v6 previews without it. Associated spend is descriptive and cannot carry or imply an avoidable amount.

​

Recommendation objects

Recommendations are created only from current findings. estimatedSavingsUsd equals avoidableSpendUsd; it is never derived from affected spend or signal metrics.

​

Current recommendation patterns

​

Legacy history

Wire v5 findings keep their original costImpactUsd, classification, and kind so historical audit and optimization records remain intact. New v5 pushes receive an upgrade advisory, remain readable, and cannot create or recur current optimization records. Current recurrence identity includes detectorVersion, preventing a same-named legacy finding from inheriting a v6 status.