---
name: reasoning-linkage-confidence
description: Classifies combinations of two or more official-statistics data units into five metadata-only confidence tiers, each mandating an action — compute silently, add a stated assumption or explicit caveat, escalate with a fixed template, or refuse. Fires when units combine for a ratio, share, difference, contribution, correlation or ranking, even when combining sources is unstated, for intermediate values never surfaced, and when series from different agencies or dataflows sit side by side. Does not do the arithmetic (guarding-derived-indicators) or compose data citations and attribution wording (citing-official-statistics).
license: CC-BY-4.0
metadata:
  author: Aard
  homepage: https://aard.ai
---

# Reasoning about linkage confidence

Two series that share a name rarely share a definition. This skill decides, from metadata alone, how much confidence a proposed combination deserves — and what the agent owes the user as a result. The tier is not a score for its own sake; it selects a mandated action.

## When to use

Only when two or more units must be combined. If `decomposing-data-questions` collapsed the question to one dataflow and key family, skip this skill entirely — that is the cheapest and safest path and should not be second-guessed.

Diagnose from metadata only, using the Aard MCP server's `inspect` tool (and `browse_dimension_codes` where a codelist is too large for `inspect` to show in full). **Never fetch observations to decide a tier.** Fetching to decide invites reasoning from the values back to their compatibility, which is exactly the inference the tier system exists to prevent.

## The taxonomy

Full table with predicates and actions in `references/units-and-tiers.md`.

- **Tier 1 SAFE** — compute silently. Same agency and dataflow; keys differ only in the compared dimensions; identical unit, price base, adjustment and reference period. One overriding exception: never sum or difference chain-linked volumes even within a single dataflow. Switch to previous-year-price or contribution keys and hand to the guard skill.
- **Tier 2 PROBABLY SAFE** — compute and state the assumption. Same producer, different dataflows; shared cross-domain codelists; no methodological divergence flagged in reference metadata.
- **Tier 3 DEFENSIBLE** — compute with an explicit caveat. Different producers, but a shared harmonised standard. Residual risk is vintage, benchmark year, derogations and revision timing.
- **Tier 4 ESCALATE** — different producers, divergent methodology, nominally the same concept. This is the clerical-review region of Fellegi & Sunter's decision rule: the zone where automated resolution is provably worse than referring the case out. Do not compute silently.
- **Tier 5 REFUSE** — no shared dimensionality supporting the operation; incompatible units with no valid conversion bridge; category errors such as a chain-linked index over a nominal level, or an unrepairable stock/flow or real/nominal mismatch.

**The tier is a floor.** Within tiers 2–4, caveat strength scales with the number and severity of divergence axes: unit, price base, adjustment, vintage, population concept, reference period, revision status. A borderline 3/4 case is treated as 4.

## Metadata predicates

Evaluate in order against `inspect` output. Match on **bound codelist identity, not concept label** — agencies vary the spelling (`PRICES` vs `PRICE_BASE`, `SEASONAL_ADJUST` vs `ADJUSTMENT`) while binding to equivalent cross-domain codelists, and a label match will mis-fire on non-OECD providers.

Before comparing series, verify that they share the same classification, revision and exact activity perimeter — not merely the same code or label. Inspect country-specific concordances and included industries, and confirm that nominal, real and other measures use the same scope. A shared codelist ID is necessary but not sufficient when country mappings sit beneath the published code. If observations retrieved after the metadata verdict disagree inexplicably with a canonical harmonised dataset, stop the comparison, invalidate the verdict and flag the discrepancy; never use agreement in observed values to promote a pair to a safer tier.

1. Same `agency_id` and same `dataflow_id`? → candidate Tier 1.
2. Do the join dimensions resolve to identical codelist IDs?
3. Are `UNIT_MEASURE`, `PRICE_BASE` and `ADJUSTMENT` codes compatible across units?
4. Same producer, different dataflow, shared cross-domain codelists? → Tier 2.
5. Different producers, shared international standard or global DSD? → Tier 3.
6. Reference metadata flags a methodological break — ESMS 15.1 comparability-geographical, 15.2 comparability-over-time, or a coherence concept? → Tier 4.
7. No shared dimensionality, no conversion bridge, or a category error? → Tier 5.

Observation-status and confidentiality flags feed predicate 3 and the gradation rule: a break flag or a confidentiality suppression on either operand raises caveat strength. Publication-symbol semantics per agency are in `references/flags.md`; SDMX `OBS_STATUS`/`CONF_STATUS` are resolved at runtime from the DSD's own code list, per the same file. An unresolved flag raises caveat strength — it does not get a default reading.

Where no structured comparability metadata is available — common outside the ESS — predicate 6 returns null and the tier defaults to **Tier 3 with caveat**, not Tier 2. Record *why* it was null, using the same distinction the data-unit schema draws: `metadata_absent=true` where you have positive grounds the producer publishes none, `metadata_unavailable=true` where none simply reached you. Both give Tier 3 here, but only the first can later stand in for an instance citation, so collapsing them costs the audit trail. Either way, a null predicate is a finding to report, not a licence to assume compatibility.

## What this skill emits

A tier verdict plus a decision record (schema in `references/units-and-tiers.md`), so a second agent can audit that the tier was assigned on cited evidence.

**Authority citation is required and belongs here.** Every tier verdict cites the methodological source grounding the tier semantics — the SDMX Glossary for the coherence/comparability distinction, Fellegi & Sunter for the Tier-4 clerical-review region — drawn from `references/source-registry.md` with authority, locator and link.

**Data citation is required and does not belong here.** The `citations[]` entries with `scope: instance`, and any user-facing source line naming a series, are built by `citing-official-statistics`. Supply it the unit set with `metadata_url`, `query_url`, `version`, `extracted_at`, `resource_title`, `resource_kind`, `resource_title_status`, `selected_members`, `selection_basis`, `selection_labels`, `selection_status`, `response_format`, `licence_label`, `licence_url` and `notes` populated; do not compose source lines, licence wording or identifier strings in this skill. This applies to Tier-4 escalations and Tier-5 refusals as much as to computed results — naming two series to the user is surfacing them, and they need citing even though nothing was computed.

Preserve those values **verbatim**. Describing comparability is this skill's job; restating a provider's title or member label in your own words while doing it is not — the label the citation renders must be the label the provider published, even where a clearer phrasing exists.

## Tier-4 escalation template

Escalation is an actionable choice, not a disclaimer. Present four slots:

1. **The candidate series** — producer, dataflow id, exact definition from reference metadata, with each producer's methodology link.
2. **The divergence** — the specific dimensions, named, with the metadata field that flagged each.
3. **The consequence** — what changes under each assumption, numeric or directional.
4. **The choice** — concrete closed-form options (a) / (b) / (c).

A case reaches this template only when predicate 6 actually fires — that is, when reference metadata *names* the methodological break. Divergence you inferred, assumed, or reasoned about from the producers' identities is not predicate 6, and does not license escalation.

### Worked example: ABS vs OECD unemployment is Tier 3, not Tier 4

This pair is the one most often mis-tiered, and working it through is more useful than a Tier-4 example would be.

Both publish an Australian unemployment rate — `ABS:LF` (Labour Force, unemployment rate, seasonally adjusted) and `OECD.SDD.TPS:DSD_LFS@DF_IALFS_UNE_M` (Infra-Annual Labour Force Statistics, `MEASURE=UNE_LF_M`, `UNIT_MEASURE=PT_LF_SUB`). Different producers, nominally the same concept — which *looks* like the Tier-4 clerical-review region.

Run the predicates instead of pattern-matching:

- Different `agency_id`, `REF_AREA` compatible — so not Tier 1 or 2.
- Both rest on the same ILO/ICLS harmonised standard, and the OECD series is a re-standardised derivative of the national one rather than an independent measurement. **Predicate 5 fires → Tier 3.**
- **Predicate 6 does not fire.** The OECD publishes no structured comparability metadata through its SDMX API, so the predicate returns null. Per the null rule above, that means `metadata_absent` and **Tier 3 with caveat — never an escalation.** A null predicate is not evidence of divergence; it is absence of evidence either way.
- Do not manufacture a divergence to justify escalating. `AGE` in particular is a trap in the opposite direction from the obvious one: the OECD flow constrains it to `Y_GE15`, `Y_GE25` and `Y15T24`, so its headline is 15-and-over — the *same* scope as the ABS headline. Age scope here is a divergence you can create by accident by selecting different codes, not a fixed difference between the producers.

**Mandated action (Tier 3).** Compute, and caveat on the residual risks Tier 3 names: vintage and revision timing, since the two producers republish on different schedules and can therefore disagree at a given vintage while agreeing at others. Do not claim they always differ. State which basis was used, and prefer the OECD harmonised series for cross-country comparison because that is what makes Australia commensurable with the other reporters in that flow.

*Dataflow IDs and the `AGE` constraint were resolved live against each producer's SDMX API. Re-resolve rather than trusting them — content constraints change.*

**A verified Tier-4 pair is not yet documented here.** It needs two producers whose reference metadata explicitly flags the break — realistically an ESS producer, since ESMS 15.1/15.2 is where that flag is reliably populated. Until one is worked through, use the four slots above as the output format and let predicate 6 decide whether you are entitled to them.

## Handoff

Pass the tier verdict, the decision record and the surviving unit set — every citation-identity field intact and unrewritten — to `guarding-derived-indicators` where arithmetic follows, and to `citing-official-statistics` wherever a number or series name reaches the user.

Where either skill is unavailable, the obligation transfers rather than lapsing, and stating the tier caveats alone does not discharge it. Without the guard skill, do not treat a tier verdict as clearance to compute — a Tier-1 pair can still be a chain-linked-volume category error, so apply the additivity, price-base and adjustment checks yourself or decline the arithmetic. Without the citation skill, do not emit a number until the producing agency, dataflow identifier, extraction timestamp, operand flags and licence wording are on it, working from `references/licensing.md`, which ships with this skill for that purpose. A tier verdict attached to an uncited figure is not a partial success.