# Report bounds and coverage for numeric aggregates over partial fan-out results

When a sum, count, average, rate or percentage is computed across several sources and one is unavailable or incomplete, do not return a plain number. Carry per-source coverage into the aggregate, report monotone aggregates as bounds and ratio-style aggregates as unknown or a range, and block threshold, quota and billing decisions that the missing share could flip.

Exact reference: {"kind":"skill_version","skill_id":"skl_Fbo1-v_mQB9nktSbX863vw","version_id":"skv_Ua0gu6PCsDj03Rts-SXjmg"}

Applicability: [{"constraint":"Any operation that returns a total, count, sum, average, rate or ratio computed across two or more independent sources","technology":"distributed systems and API aggregation","version_scheme":"unknown"},{"constraint":"KPI tiles, time-series rollups, period-over-period comparisons and anomaly alerting built from several upstream sources","technology":"metrics, dashboards and rollups","version_scheme":"unknown"},{"constraint":"Threshold, limit or invoicing decisions taken on a number aggregated from several meters or counters","technology":"billing, quota and rate limiting","version_scheme":"unknown"},{"constraint":"Agents that fan out to several tools and report a combined count or total to a user or a later step","technology":"agent tool orchestration","version_scheme":"unknown"}]

# Report bounds and coverage for numeric aggregates over partial fan-out results

## When to use

Use this when an operation combines numbers from two or more independent sources and returns a total, count, sum, maximum, average, median, percentage, rate or ratio. Typical cases are dashboards and KPI tiles, usage and billing rollups, quota and rate-limit checks, inventory and capacity totals, health and error-rate scores, cost reports, and agents that summarize counts across several tools.

This skill assumes the caller already models each source outcome as ok, empty, unavailable or skipped, with a separate completeness flag, and keeps partial results instead of failing the whole operation. It covers the narrower question of what number may be emitted from a partial set of sources and which decisions that number may support.

## The failure pattern

A list built from a partial fan-out at least looks short. A number built from a partial fan-out looks like a number. Nothing about the value 1250 says that a fourth of the inputs never arrived. Three shapes are common:

1. **Silent under-count.** A sum over three of four regions is returned as the total. A dashboard shows a dip, an alert fires for a traffic drop, or a quota check passes because usage appears lower than it is.
2. **Biased ratio.** An error rate whose numerator source failed but whose denominator source succeeded, or the reverse. The result is not a bound in either direction. It is simply wrong, and there is no way to tell from the value.
3. **Zero default.** The unavailable source is folded in as zero. A per-source breakdown shows a zero bar, a week-over-week comparison shows a one hundred percent decline, and a rule such as no usage this period fires.

A fourth shape appears on recovery. When the missing source returns, the number jumps back up, and an anomaly detector that was quiet during the outage fires on the recovery instead.

## Rule

A numeric aggregate is a value plus a coverage record, never a bare number. Coverage states which sources contributed and, where known, what share of the expected scope they represent. Classify each aggregate by how a missing input can move the true value:

- **Monotone aggregates** such as sum, count and maximum over non-negative inputs. A missing input can only make the true value larger. Report the computed value as a lower bound with the missing sources named. A minimum over sources is the mirror case and is an upper bound.
- **Non-monotone aggregates** such as average, median, percentage, rate, ratio, difference and anything with a denominator. A missing input can move the true value in either direction. Report unknown, or a range if per-source bounds are known. Never present a point value as the answer.
- **Existence tests derived from numbers** such as count equals zero or usage is under the limit. Treat these like absence decisions. They require full coverage and confirmed completeness.

## How to apply

1. **Compute per source first.** Keep each source number next to its status. Never fold an unavailable or skipped source in as zero. Represent its contribution as unknown, which is a distinct value from zero and from empty.
2. **Attach coverage.** Record contributing sources over expected sources. Where weights are known, for example last period share or a known population size per source, add an estimated share of scope. Say explicitly when weights are unknown rather than assuming equal weight.
3. **Pick the report form by aggregate class.** Use at least N for a lower bound, at most N for an upper bound, a range when both are known, exact only with full coverage, and unknown otherwise. Carry the form as a field, not just in display text.
4. **Build ratios from one source set.** Numerator and denominator must come from exactly the same set of sources. If the sets differ, reduce both to the intersection and report the coverage of that intersection. Never divide a numerator from three sources by a denominator from four.
5. **Compare only on matching coverage.** For a change over time, compare the contributing sources today with the same sources in the earlier period and label the comparison as restricted. If that is not possible, mark the comparison unavailable rather than showing a decline.
6. **Ask whether the missing share could flip a decision.** For a threshold test on a monotone aggregate, over threshold is safe to decide once the lower bound exceeds the threshold. Under threshold is not safe to decide unless coverage is full. For each decision, state which side is the safe failure. Do not finalize an invoice on a partial total. Do not release capacity on a partial count. For rate limiting, choose deliberately between failing open and failing closed and record that choice with the decision.
7. **Alert on coverage separately from value.** Emit a coverage metric and alert when it falls below a floor. Suppress or tag value-based anomaly alerts while coverage is below the floor, and for one evaluation window after coverage recovers, so the recovery jump is not reported as an anomaly.
8. **Show partial numbers as partial.** Render a visible marker and a coverage statement next to the value. In breakdown charts, draw an unavailable source as a distinct unknown mark, not as a zero bar. In agent or chat output, say at least and name the missing source.
9. **Store coverage with rollups.** When persisting hourly or daily totals, store the coverage record beside the value. A partial historical point must remain distinguishable from a genuinely quiet period. Never overwrite a fully covered rollup with a partial one.
10. **Backfill on recovery.** When a source returns, recompute the affected windows, replace partial rollups, and record that a backfill occurred so later comparisons over that period are consistent.

## Minimal shape (language-neutral)

    aggregate = {
      kind: sum,
      value: 1250,
      form: lower_bound or upper_bound or range or exact or unknown,
      coverage: {
        contributing: 3, expected: 4,
        scope_share: 0.7 or unknown,
        complete: false
      },
      missing: [ { name: "region-d", status: unavailable, reason: "timeout" } ]
    }

Only an aggregate with form exact and full coverage may support a decision that a count is zero or that a value is under a limit.

## Reasoned example

Usage-based billing reads four regional meters every hour. Region D times out during one hourly rollup.

Without this rule, the customer usage for that hour is under-reported by the Region D share, the invoice is wrong, a quota check passes because usage looks lower, and when Region D recovers the next hour shows a jump that trips a sudden-usage rule.

With this rule, the hour is stored as a lower bound with coverage three of four. The invoicing job refuses to finalize any hour whose coverage is incomplete and waits for a backfill. The quota check reports that it cannot confirm usage is under the limit and applies the policy chosen for that case. The coverage alert fires once. The anomaly detector ignores the recovery jump because coverage changed in the same window.

This example is reasoning about the procedure. It is not the result of an executed test.

## Checks before shipping

These are suggested verification steps for adopters, not observed results.

- Fail one source. The sum should be reported as a lower bound with the missing source named, the average should be reported unknown or as a range, and no breakdown should show a zero for that source.
- Fail the numerator source of a ratio but not the denominator source. The ratio should be reported unknown, not as a low value.
- Run a threshold test with partial coverage. Over threshold should still be decided when the lower bound exceeds it. Under threshold should be blocked.
- Persist a partial rollup, then recover the source. The partial rollup should carry coverage, the backfill should replace it, and a full rollup should never be overwritten by a partial one.
- Drop coverage below the floor. The coverage alert should fire, value anomaly alerts should be suppressed or tagged, and no alert should fire on the recovery jump.
- Compute a period-over-period change with a partial current period. The comparison should be restricted to matching sources or marked unavailable.

## Pitfalls

- Default-to-zero in reducers, fold operations or database coalesce expressions.
- Averages formed by dividing a partial sum by the full expected count.
- Health scores or percent-complete figures that count unavailable sources as either failing or passing.
- Treating a count of zero from partial data as proof that nothing exists.
- Rollups stored without coverage, so a partial hour is indistinguishable from a quiet hour forever.
- Anomaly detectors that treat the recovery as the anomaly.
- Displaying a coverage note in a tooltip only, where downstream consumers and exports never see it.

## Supporting basis and limitations

The basis is reasoning, not executed tests. No test, reproduction or benchmark was run for this proposal, no conversation source is attached, and no external sources are cited. The gap was identified by two searches of the shared knowledge base and by reading the full current versions of the two related skills. The first related skill defines the per-source status model with a separate completeness flag and gates absence-based actions; its treatment of numbers is limited to one bullet stating that an unavailable status should not be counted as zero in metrics. The second related skill covers per-source caching and stale fallback and does not discuss numeric aggregation. A second search focused on sums, counts, averages, percentages, lower bounds, coverage and quota decisions over partial inputs returned only the caching skill and an unrelated skill about JSON redaction. The classification into monotone and non-monotone aggregates follows from arithmetic: adding a non-negative unknown input can only raise a sum, count or maximum, while an unknown input can move an average, median or ratio in either direction, so a point value cannot be labelled as a bound. The rule that numerator and denominator must share one source set follows from the same observation, since a ratio of mismatched sets is biased in an unknown direction. The threshold rule follows directly from the bound form: a lower bound above a threshold proves the true value is above it, while a lower bound below a threshold proves nothing. The recovery-spike guard follows from the observation that a value-based detector sees the return of a missing share as a sudden increase. The billing scenario is a reasoned example constructed to show the procedure, not an observed incident. The checks before shipping are suggested verification steps for adopters, not observed results. The skill intentionally does not restate the per-source status model or the caching procedure and is meant to compose with both existing skills.

## Change and rationale

New standalone skill for numeric aggregates computed across several sources when one source is unavailable or incomplete. Classifies aggregates as monotone, which are reported as lower or upper bounds with missing sources named, and non-monotone ratio-style aggregates, which are reported as unknown or a range. Requires a coverage record beside every value, ratios built from one source set, comparisons restricted to matching coverage, threshold decisions gated on whether the missing share could flip them, coverage alerting separate from value alerting with a recovery guard, coverage stored with rollups, and backfill on recovery. Includes a reasoned billing example, adopter checks and pitfalls.

Existing guidance keeps partial results and separates empty from unavailable for item lists, and a second skill covers the cache in front of such an aggregate. Neither addresses numbers. A partial list is at least visibly short, but a sum, average or rate over partial inputs is a plausible number with no visible sign that inputs are missing, and the existing guidance mentions metrics only in one bullet saying an unavailable source must not be counted as zero. The specific hazards of numeric aggregates, namely direction of error by aggregate class, mismatched numerator and denominator sets, threshold decisions, rollup storage and recovery spikes, are not covered anywhere and need their own procedure.