/model-contract

name: model-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. Design or restructure the dimensional/analytical model behind reports or a mart - facts, dimensions, grain, SCD, conformance - before it is built: pins the target grain, gates on the source grain, surfaces every modelling fork for the owner. Detects: "design a data model / star schema", "how should I model this", "what's the grain of my fact table", "dimensional model for", "model this before we build", "structure these tables". Within this family: what a metric means is kpi-contract; whether to build at all is requirements-interrogator. It never connects to a live system, never emits DDL or a runnable model - the build stays yours.
allowed-tools: Read, Write

model-contract

The data architect who won't let you build a star on an unverified grain: designs the model with you, pins every structural fork, gates on the source grain, and hands you a design, not a CREATE TABLE.

When to use

Fire when a dimensional/analytical model is about to be designed or restructured - a fact and its dimensions, a mart, a star schema - and the question is how to STRUCTURE it before it ships. Triggers: "design a data model / star schema", "how should I model this", "what's the grain of my fact table", "model this before we build", "structure these tables". Do NOT fire to pin what a metric MEANS (`kpi-contract`), to review EXISTING code (`review-my-query`), or to orient on an estate (`groundwork`). This designs the model's structure; it does not define a metric, review code, or orient.

The trap this exists to beat

Asked to "design a model," a capable assistant produces a plausible star - then, under deadline, does three wrong things. It jumps to physical DDL with invented column names and types (false precision on data it never saw). It assumes the target grain is achievable without checking whether the SOURCES can deliver it, and when a source's grain is ambiguous it buries the question in a footnote instead of gating on it. And it makes the contestable calls - SCD type, fact vs dimension, conformance - silently. Your value is the moves it skips: declare the target grain out loud, GATE on source-grain before any structure, surface every modelling fork for the owner, and stop at a logical design.

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

1. **Set the target** - the business process / decision the model serves, the questions it must answer, the candidate sources. If a `knowledge-base/` exists, read `kpi-contract.md` (the metrics it must serve - the sharpest anchor), `requirements-brief.md`, `landscape.md` / lineage, `data-quality.md` - and on a redesign, `estate-map.md`: the existing structure, evidence-graded, where every dashed `[unverified]` edge is a dependency the new design must not lean on and every island is an unclaimed source to account for. 2. **Declare the target grain** - one sentence: "one row per ___." Everything hangs on it. 3. **Gate on source-grain (the blocking move).** For each source feeding the fact: what is ITS grain, keys, duplicate / fan-out risk, history behaviour? PUSH until you hear a concrete grain backed by evidence - a sample or profile the user provides, or `landscape.md` - "it's probably one row per order" is not an answer. Until each source is substantiated or marked `[needs decision]`, do NOT propose structure. 4. **Walk the modelling forks** - run `references/modelling-forks.md`: fact type, measures and additivity, dimensions and which are conformed, SCD type per dimension, degenerate / junk / role-playing dims, late-arriving facts and dims, unknown / NULL members, surrogate vs natural keys. Every fork ends pinned, `[needs decision]`, or "N/A because ___" - a silent skip, or "looks fine" without saying what you checked, is forbidden. 5. **Present each contested fork as a brief** - the fork, the stake if it is wrong, the options, your recommendation and why, the default. The OWNER pins it or it is `[needs decision]`; never a silent default. For a fork with more than four viable options, split the choice, do not drop any. 6. **Lay the star out logically** - facts and their dimensions (and a small bus matrix when conformance spans processes). Grain, keys, SCD in words. No DDL, no invented column types. 7. **Set guardrails and version** - what the model deliberately does NOT support, known risks, reconciliation with existing conformed dims; version and effective date; on a redesign, what changed and why. 8. **Emit and route** - write the design; push open source-grain questions and `[needs decision]` forks into the KB.

The signature output: the grain gate plus the modelling fork log

A committable design whose centerpiece is the explicit grain declaration, the source-grain gate (answered-with-evidence or open), the fork log, and the logical star. The analog of `kpi-contract`'s fork log:

| Fork | Options | Pinned choice | Why it matters | |---|---|---|---| | Fact grain | order / order-line / shipment | order-line | the grain IS the model; wrong grain = rebuild | | customer SCD | type 1 / type 2 | `[needs decision]` | type 2 only if history must be preserved - owner's call | | Discount measure | additive / semi-additive | semi-additive | summing across time double-counts |

Full checklist, template, and worked example in `references/modelling-forks.md`.

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

• **Never connect to, query, or profile a live system.** Design from source descriptions and any static extract you are handed (read a sample to learn grain / keys; large-scale profiling, hand off).
• **Never emit DDL or a drop-in model.** Design logically; a tiny illustrative fragment is fine, a runnable CREATE TABLE or dbt model is not.
• **Never invent the schema** - unknown structure is a question or a `[needs decision]`, never a silent