The deploy contract isn't a YAML file
The most important artifact a research engineer ships is also the one that doesn't look like code. It looks like the conversation that happened the week before.
Every research framework I’ve worked on has had a moment where someone — usually a quant — asks “so what do I actually have to write down to get my model into production?” The honest answer is that the framework can probably enforce ten different things, but only three or four of them matter, and which three or four matters more than the enforcement mechanism.
That short list is the deploy contract. It’s the most important artifact a research engineer ships, and it doesn’t look like code.
What it actually is
A deploy contract is the set of declarations a model must make before it can be promoted. In a healthy team it’s three to six items, each defended by a story about what went wrong without it. For a mid-frequency alpha platform, mine usually looks like:
- the feature graph hash the model was trained on
- the training data window (start + end, inclusive)
- the evaluation report — signed by the framework, not the author
- the owner team — exactly one, with an on-call rotation
- the expected operating envelope — gross / net exposure bounds, expected daily turnover, expected freshness SLO
That’s it. Five lines on a sheet of paper. Everything else the framework checks is downstream of these.
What it’s not
It’s not a YAML file. A YAML file is how the contract is encoded after the conversation. If the YAML file appears first, the contract isn’t a contract — it’s a unilateral demand wrapped in a parser.
It’s not a checklist either. Checklists go stale; their items get copy-pasted across models without thought; the friction of declining to fill in a field is lower than the friction of arguing about whether the field is the right one. A real contract has each item defended — by a written incident, a near-miss, or a concrete story from the team’s recent past.
How it gets written
Three things have worked for me, in order.
1. Write the first draft alone and then throw it away.
You don’t have the context yet, but you have to know what you’d write to know what’s missing. Spend a morning on it. Read it. Notice which items you can defend with a story from this team and which are imported from a previous job. Delete the imported ones.
2. Walk it through, separately, with the two most prolific researchers and one senior trader.
Separately, not together. The first time someone sees a contract shouldn’t be in a room with other senior people they’d rather not contradict in public. The questions you want are “what would this have caught last quarter?” and “what would this have prevented that I’d actually want to allow?” — both are signal.
3. Bring the merged draft to the team.
Once you have a draft that survived three independent reads, the team meeting is a different conversation. It’s not “convince us” — it’s “here’s what your colleagues already said; here’s what they disagreed about; what should we do about the disagreements.”
What I’ve seen go wrong
The two most common failure modes:
Over-specified. A contract with twelve items has thirteen implicit items, because the team will work around the twelve to preserve the implicit ones. Cut hard. If you can’t tell a story about an item, it’s not on the list yet.
Under-defended. A contract whose items are not paired with stories ages into folklore — three years later someone is checking a box because “we always have.” That’s how compliance becomes a performance instead of a property. Every item should have a written paragraph explaining what would happen without it; that paragraph should be updated when the story it tells changes.
Why this matters more than the framework
A framework is the thing that enforces the contract. The contract is the thing the team agrees on. Switch frameworks and a good contract survives; switch teams and a good framework without a contract becomes shelf-ware.
A research engineer who can write the framework but can’t write the contract has built a tool. A research engineer who can do both has built a platform. The job description for the role I’d take is the second one.
Companion reading: the model-registry writeup is the code side of this story; the first-90-days plan puts the contract conversation in phase 3 deliberately — you don’t earn the right to write it in phase 1.