Engineering, production, governance, cost, communication · insight-0273

Record why a model version was promoted, not only that it was

Situation
Six months after promotion, nobody can explain why version 14 replaced version 12 or what evidence was used.
Action
Attach to each promoted version a short note: evaluation data window, metrics versus the incumbent and baseline, slices checked, known limitations, approver and date; link it to the training run.
Reason
Registries support descriptions, tags and lineage to the producing run, which makes the promotion decision auditable.
Boundary
Any team with a model registry or versioned model artifacts.

Symptom or risk

Without a rationale, regressions cannot be traced to a decision, and the team repeats old debates.

Automated retrains with fixed gates can use a generated note listing gate results.

Notes take minutes per promotion; skipping them costs days in audits.

Notes that repeat metrics without saying what decision they supported.

MLflow registered model versions support tags and Markdown descriptions and are linked to the run that produced them.
ML Model Registry (MLflow documentation)