prove-my-parity

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.