A change request moves an order service's workload spec from three copies to six and swaps its image digest — what can the reviewer conclude, and what must they check elsewhere?

## What the diff actually proves A workload spec is reviewable in a way that a sequence of operator commands never is, and this is the main reason teams keep one. Because the document states the end state rather than the route to it, a diff over it has three properties worth naming: - **It is complete about intent.** Every field not in the diff is being asserted unchanged. There is no hidden step, no ordering, no side effect expressed anywhere else in the document. - **It is exact.** "Three copies became six" and "this image identity became that one" are the whole of the proposal, in terms a reviewer can argue with before anything runs. - **It is reversible on paper.** The pre-change document is a complete statement of the old intent, so a revert is a well-defined artifact rather than a reconstruction from memory. So the reviewer can conclude: the team wants six copies of exactly these bytes, and wants nothing else about this workload changed. ## What the diff cannot tell you - **Whether it will be satisfied.** The spec is a want. Six copies at a declared reservation of 512Mi each is 3Gi of memory spoken for, against 1.5Gi before; if the cluster's unreserved capacity cannot take the extra three, the change is approved, merged and partly unplaced. The diff contains no capacity argument and cannot contain one. - **What is running today.** Live state is a separate document, written by the platform. A reviewer who wants to know whether the three copies are even healthy has to go and look. - **Whether it was ever applied.** A merged change and an applied change are different events; the document can sit in the repository well ahead of the cluster. - **What the new bytes do.** A digest swap is reviewable as a *pin* — it is exact, and it is the same bytes everywhere — but the diff says nothing about whether that build starts, whether it still fits its ceiling, or whether it can read the data the old one wrote. - **The fields nobody wrote.** Defaults do not appear in a diff. A workload that declares no ceiling may still get one; a workload that declares no reservation may be treated as free to place. The effective object is what applies, and it is not what was reviewed. - **How the change reaches the running copies.** The order, the batch size and the pauses between them are a separate subject with separate settings; the diff shows the destination only. ## The invisible half The gap between the reviewed file and the effective object is the part that catches experienced teams. Platforms differ here — some inject a set of scope-level defaults into every workload, others leave unwritten fields genuinely empty — so the only reliable habit is to read the stored object for anything load-bearing rather than to trust the review as a full picture. A reviewer who wants to assert something about a ceiling asks for the ceiling to be written into the document, because a field that is written is a field that will show up in the next diff. ## A review checklist for this diff 1. **Multiply.** Copy count times reservation is the change in aggregate demand; six copies at 512Mi is 3Gi. Ask whether that is available, and ask it about the failure domains the copies are meant to spread over, not just the cluster total. 2. **Separate the two changes.** A count change and an image change in one request means a single revert cannot undo one without the other, and an incident afterwards has two candidate causes. 3. **Ask what is live.** Compare the intent being proposed with the status being reported now; a count increase on a workload that cannot keep three healthy is not a capacity change, it is a bigger version of an existing problem. 4. **Name the unwritten fields that matter.** Anything the reviewer would defend in an incident — the ceiling, the storage access mode — belongs in the document rather than in a default. 5. **Ask what a revert means.** Reverting the document restores the old intent; it does not instantly restore the old running copies, and it does not undo anything the new build wrote to durable storage. ## The two documents, the two questions | Question | Where it is answered | |---|---| | What does the team want this workload to be? | the declared spec, and the diff over it | | What is this workload right now? | the live status the platform writes back | | Will the want be satisfied? | neither one alone — the want measured against free capacity | | What changed, and who approved it? | the change request over the spec | The reason a spec is worth reviewing at all is that the first row has a stable, complete answer written down before anything happens. The mistake is to let that stability read as a guarantee about the other three rows.