/triage-my-number

name: triage-my-number
description: Use when the work is hands-in-the-data right now — a number moved, an open question needs exploring, a picture of the estate needs drawing, a change needs its blast radius known. A number or result is wrong, suspicious, or moved unexpectedly in production and the why must be found before it is explained - a KPI that jumped or cratered, two reports that won't reconcile, a figure no one trusts. Drives a systematic differential across the whole failure surface - code, data, pipeline, definition, or a genuinely real change - so the first plausible cause is not taken for the confirmed one. Detects: "why is this number wrong", "revenue/churn jumped, why", "these two numbers don't match", "the dashboard looks off", "did something break overnight". Within this family: no wrongness symptom, just an open question, is explore-my-data; drawing the estate is map-my-estate. Never runs a query or touches a live system; the only computation is a tested decomposition kit on summary counts you provide.
allowed-tools: Read, Write, Bash

triage-my-number

The colleague you grab when a number comes out wrong: helps you find out *why* it moved before you tell anyone *what* it means — systematically, without tunnelling on the first guess or reaching for the data yourself.

When to use

Fire when a number, metric, or result is wrong, suspicious, or moved unexpectedly and the question is "why" — before it gets explained to anyone. Triggers: "why is this number wrong", "churn/revenue/signups jumped — why", "these two numbers don't match", "the dashboard looks off", "this doesn't reconcile", "did something break overnight". Do NOT fire to review a specific query you already suspect (that's `review-my-query`), to pin what the metric should mean (`kpi-contract`), to orient on an unfamiliar estate (`groundwork`), or to rehearse defending a finished number (`defend-my-number`). This diagnoses *why a result is wrong* across the whole path; the code is only one branch of the differential. **This vs. its neighbors:** the gate is a *symptom in hand*. Fire when a number is already wrong/moved and you run the whole 5-branch differential to find the cause. *No symptom yet — about to build on or present a number whose premises are unexamined* → `audit-my-assumptions` (preventive, upstream). *A specific query to check* → `review-my-query`.

The trap this exists to beat

Asked "why is this number wrong," a capable analyst does the analytical part well — reads the code, names plausible causes. Then, under the pressure that always comes with a broken number ("the board call is in 90 minutes"), it does two wrong things. It **tunnels**: it latches onto the most-likely cause and writes it into the story for leadership before a single check ties it to *this* number. And it **lunges at the data**: handed a sample "to see the shape," it computes — runs the logic over the rows "just to confirm the mechanism" — crossing the read-only line. The result is a confident cause that is really a *suspect*, handed to a stakeholder as a verdict. This skill holds the differential: it enumerates the whole failure surface, attaches a discriminating check to each candidate, keeps "a defect you can read" separate from "the cause of this number," directs *you* to run the checks, and gives the stakeholder a calibrated holding line — not a guess.

The loop

1. **Frame the symptom + harvest context** — pin what's wrong vs expected, *since when*, and the *scope* (one metric? one segment? everything?). If a `knowledge-base/` exists, read `kpi-contract.md` (what the number is *supposed* to be), `query-review.md` (known defects), `data-quality.md` / `notes.md` (known issues), `landscape.md` (what feeds it) — and the change record: `timeline.md` plus any recent `change-impact.md`. A blast radius that predicted a SILENT-DRIFT or BREAK on this very metric is a pre-computed prime suspect — its pre-flight check becomes your first discriminating check, ahead of the cold differential (which still runs in full: a prediction is a suspect, not a conviction). No wrong-result symptom in hand? Wrong skill. 2. **Bound & decompose before diagnosing** — establish when it started and the blast radius, then **decompose the metric** (numerator vs denominator, by segment / source / time). "Did the numerator jump or the denominator shrink" splits the hypothesis space fastest and tells you which half to chase. With the counts in hand, COMPUTE the split via the kit (`decompose_rate`, `mix_shift` in `references/triage_checks.py`) — don't eyeball which leg moved. Do this before naming any cause. 3. **Run the differential (the engine)** — enumerate the *whole* failure surface, don't stop at the first hit: see `references/failure-surface.md`. Branches: **code** (reuse `review-my-query`'s taxonomy — grain/filter/NULL/time/SCD), **data** (late-arriving, backfill, an upstream/source change, a new value), **pipeline** (partial load, failed step, stale refresh, cache), **definition** (drift; someone changed it), and **real change** (it's genuinely true). Attach a *discriminating check* to each candidate. 4. **Prioritise the checks — and hand them to the user** — order cheap-and-splitting-first; tell the user exactly what to run. You do not run it. Keep **a defect you can read** (the code *can* do this) separate from **the cause of this number** (a check ties that defect to *this* symptom). 5. **Converge or loop** — interpret what the user brings back; rule candidates in or out. Don't declare a cause until a check ties it to the symptom; if none does yet, refine and re-check. 6. **Emit + hand off** — write `triage.md` (the differential, the checks, what's confirmed vs open, the calibrated stakeholder line). A confirmed code defect hands to `review-my-query`; a definition gap to `kpi-contract`; a confirmed **definition-drift cause on an inherited source** hands back to `audit-my-assumptions` to re-clear the foundation. If a `knowledge-base/`