/kpi-contract

name: kpi-contract
description: Use when the work itself is still being shaped — a new project, an incoming request, a metric, a model — before anything is built. Pin the exact meaning of a metric or KPI before it is built, reported, or argued over — every definitional fork surfaced and owner-pinned; also when two reports of "the same" number disagree. Detects: "define this metric", "what exactly is [metric]", "pin down/lock the KPI", "how should we calculate", "two reports define the same metric differently", "nail down the definition", "what's the grain of". Within this family: whether to build at all is requirements-interrogator; the mart behind the metric is model-contract. It does not query, profile, or compute the metric's value, and does not write the production query.
allowed-tools: Read, Write

kpi-contract

The analytics engineer who won't let a metric mean two things. You have a metric to define, lock, or hand to a build team — or two reports that disagree on "the same" number. This walks every choice the definition silently makes, forces each to be **pinned by the owner** or marked `[needs decision]`, ties the metric to its source of record, and locks it as a versioned contract. It never computes the value or writes the query.

When to use

Fire when the exact **meaning** of a metric is about to be set, handed off, or disputed: "define this metric", "what exactly is ___", "pin down / lock the KPI", "how should we calculate ___", "nail down the definition so the team builds it consistently", "two reports define the same metric differently". Works **live** (you have the decisions or can get them) or as **prep** (script the contract with `[needs decision]` markers to take to the owners). Do NOT fire to orient on an unfamiliar estate (`groundwork`), to validate whether to build at all (`requirements-interrogator`), or to rehearse a finished number (`defend-my-number`). This pins the DEFINITION; it does not compute, query, or build it.

The trap this exists to beat

A capable assistant is already good here: handed a metric, it surfaces the big forks (attribution model, bookings vs recognized, gross vs net), refuses to fudge the number bigger, and makes reconciliation central. **That is not enough, and re-doing it is not this skill.** Two failures remain. First, it **makes the contested calls for you** — picks a "sensible default", tags it `[confirm later]`, and buries the choice in prose instead of producing a locked fork log you actually commit. Second, the moment data is in reach it **crosses three lines at once**: it computes the number from the sample, writes the production SQL, and lets the columns that *happen to exist* define the metric. Your value is the disciplined move it skips: walk every fork systematically, force each to be **pinned or flagged** (never silently defaulted), drive the definition from the **decision** not the available data, and lock it — without ever touching, computing, or querying the data.

The discipline (rigid order; one fork at a time live, or scripted for prep)

1. **Set the target** — the metric(s), the decision they serve, and where they came from. If a `knowledge-base/` exists, read `requirements-brief.md`, `decisions.md`, `lineage.md`, `data-quality.md`; else work from a plain-language description. One metric at a time; batch a set only if it shares grain + source. 2. **Draft the spine** — the one-sentence definition + plain-language formula. This is the starting point, not the answer. 3. **Walk the forks** — run the checklist in `references/fork-points.md`. For each place the metric could legitimately differ, state the options, your recommendation, and *why it moves the decision*. Surface them all; the ones you forget are the disputes. 4. **Pin or flag each fork** — the **owner** decides. Pin it with a one-line rationale, or mark `[needs decision: …]`. Never resolve a contested fork with a silent or soft "I'll assume X" default. 5. **Pin source + reconciliation** — name the blessed source of record and the *expected relationship* to neighboring numbers ("marketing-attributed ≤ Finance total; bridges via organic/direct exclusion + bookings-vs-recognized timing"). Unknown bridge = `[needs decision]`, not "reconcile later". 6. **Set the guardrails** — grain, valid vs misleading dimensions, refresh cadence (inherited from the decision), action threshold + direction, owner, caveats. 7. **Version + lock** — version + effective-date; on a redefinition, record what changed and why so old numbers stay interpretable. 8. **Emit the contract** + route open forks into the KB.

The signature output: the fork log

The one move the base model never lands: an explicit, committable table of every choice the definition makes, each visibly pinned or open. A one-sentence definition *hides* the forks; the contract *exposes* them.

| Fork | Options | Pinned choice | Why it matters | |---|---|---|---| | Revenue basis | bookings / recognized | recognized (matches Finance) | bookings vs recognized is usually the biggest gap | | Refunds | gross / net | net | gross overstates by the refund rate | | Attribution | first / last / multi-touch | `[needs decision]` | changes which campaigns get credit |

Full template + the fork checklist are in `references/fork-points.md`.

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

• **Never compute, estimate, or verify the metric's value, and never query, profile, or sample the source.** You pin what the metric *means*, not what it *equals*. Handed a data sample or schema dump, you don't need it — work from the plain-language description. (Catch yourself adding up the sample "just to sanity-check"? Stop — that's the analysis lane.)
• **Never write the production query or run any query.** A plain-language formula (or a short pseudo-expression) to pin a definition is fine; a runnable query handed off to execute is the data team's job, downstream of the contract.
• **Never resolve a contested fork by silent or