/prove-my-parity

name: prove-my-parity
description: Use when a measured result — an experiment, a forecast, a number that must tie out — is about to drive a decision; the validity checks run before the decision does. Two systems or eras claim the same number and must be PROVEN to agree — a migration cutover (legacy vs new), a month-end tie-out. Comparability gate FIRST (same definition, population, window, grain, units — or the tie-out is invalid), tolerance pinned with its owner BEFORE results, compares by STRATUM via a tested kit (matching totals over offsetting segment errors = FAIL), every residual decomposed — unexplained above tolerance blocks sign-off. Detects: "prove the new system matches", "reconcile CRM and billing", "migration parity", "the totals match". Within this family: an A/B result is audit-my-experiment; a forecast is audit-my-forecast. Boundary: WHY one number moved is triage-my-number. Never connects to either system.
allowed-tools: Read, Write, Bash

prove-my-parity

The controller who never signs a tie-out on the grand total: parity is proven stratum by stratum, against a tolerance someone owned before the numbers arrived, with every residual carrying a name.

When to use

Fire when agreement between two stated numbers must be PROVEN — a migration cutover gate (legacy vs new mart), a recurring tie-out (CRM vs billing vs GL, month-end), vendor-vs-internal, pre/post replatform — working from the summary numbers (by stratum) and definitions you provide. Do NOT fire to find WHY one production number moved (`triage-my-number` — that is a symptom investigation; this gates a claimed agreement), to audit the knowledge base (`kb-reconcile`), to validate an experiment or forecast (its Validate siblings), or to pin what the metric means (`kpi-contract` — though this skill will send you there when the two sides' definitions differ). This proves or fails a tie-out; it does not diagnose, audit records, or define metrics.

The trap this exists to beat

Asked "the totals match — are we good to cut over?", a capable model checks the two grand totals, sees 0.01%, and says yes. Four failures hide in that yes. **Offsetting errors** — region A overstates by the same amount region B understates; the total is perfect and both segments are wrong; the grand total is the LEAST informative number in any tie-out. **Tolerance-by-vibe** — "close enough" without a pre-agreed bound is a feeling; whoever owns the number owns the tolerance, and it gets pinned before results are seen. **Comparability theater** — the two systems' "revenue" are different contracts (one includes shipping fees); agreement between non-comparable numbers is coincidence, not parity. **The hand-waved residual** — "probably rounding" is a classification someone must defend, not a default. This skill gates on comparability, computes the strata, and reserves "parity" for what the ledger can prove.

The loop

1. **Pin the claim.** Which number, which two (or N) sides, as-of which window, gating which decision (cutover / month-end close / vendor trust). Deploy or close-date pressure is recorded, never obeyed. 2. **Comparability gate (before any number is compared).** Side-by-side the two definitions: population, filters, window, grain, units/currency, timing basis (booking vs cash, event vs load date), rounding. ANY difference is documented and mapped — or the tie-out is declared invalid until the definitions are aligned (route the definitional dispute to `kpi-contract`). Agreement between non-comparable numbers is not parity. 3. **Pin the tolerance — with its owner, before results.** Absolute AND relative bounds, per stratum and for the total; zero for counts unless the owner justifies otherwise; who accepted it, dated. A tolerance proposed after seeing the gap is a rationalization. 4. **Compare by stratum (the kit — `references/parity_checks.py`).** Run `stratified_diff` on the per-stratum pairs you provide (region, month, product, entity — whatever the number decomposes by). The offsetting flag is the point: **total within tolerance while any stratum fails = FAIL**, stated as such. Missing strata data becomes the exact extract you run and paste back. 5. **Decompose every residual.** Each gap classified — timing / population / definition / units-FX / duplicates / genuine defect — with `residual_summary` keeping the arithmetic honest: the UNEXPLAINED remainder above tolerance blocks sign-off, every time. A defect found routes to `triage-my-number` or `review-my-query`; a definitional cause routes to `kpi-contract`. 6. **Verdict + emit.** **PARITY** (all strata within the pinned tolerance) / **QUALIFIED** (within, with named residuals the owner accepted in writing) / **FAIL** (the decomposed gap ledger and what would clear it). Write `parity-proof.md` (template: `references/parity-proof.md`) with its `Re-audit when:` (next period / next cutover step); a false-pass stopped gets its `catches.md` line; offer the `kb(prove-my-parity)` commit. Then stop — the fix and the cutover call are yours.

The signature output: the stratified parity proof

A tie-out where the verdict rests on strata, not totals; the tolerance has an owner and a date earlier than the results; and every residual dollar is classified or blocking. "The totals match" is the start of the work, not the end of it. Kit semantics and the worked example live in `references/parity-engine.md`.

Bright lines (non-negotiable; inherits groundwork's read-only line)

• **The grand total alone never passes a tie-out.** Strata or it didn't happen; the offsetting flag is computed, not eyeballed.
• **No tolerance after the fact.** Pinned with its owner before results are seen, or the comparison is exploratory, not a proof.
• **Comparability before comparison.** Differing definitions invalidate the tie-out until mapped — agreement between different contracts is coincidence.
• **Unexplained blocks sign-off.** Above tolerance, "probably rounding/timing" without the decomposition is