resource-control/docs/optimization-cases.md

# Optimization cases — review cadence and decision template

`resource-control` produces optimization cases. It does not approve them and it
does not implement them. A case turns portfolio evidence into a reproducible
comparison; a human or repository authority decides; the owning platform or
workload repository implements; `fin-hub` records the money.

Schema: `schemas/optimization-case.schema.json`.
Evaluator: `tools/optimization.py`. Cases live in `data/optimization/`.

## Case types

| Type | Question it answers |
|---|---|
| `rightsizing` | Is provisioned capacity materially larger or smaller than sustained demand? |
| `consolidation` | Can separate resources share one substrate without breaking failure domains? |
| `commitment` | Does a term or reserved commitment beat on-demand pricing at forecast demand? |
| `renewal` | Should this contract renew, renegotiate, or lapse? |
| `migration` | Should the workload move to different capacity at the same provider? |
| `retirement` | Is this resource still serving anything? |
| `provider_switch` | Should the same service come from a different provider? |

## Decision template

Every option — the baseline included — must present the same fields. The
baseline is a full option, not a footnote, because a comparison against an
undescribed status quo is not a comparison.

1. **Baseline** — what is in place now, on the same terms as every alternative.
2. **Alternatives** — at least one, each independently costed.
3. **One-time cost** — migration, setup, dual-running, and the labour to do it.
4. **Recurring cost** — split into infrastructure, internal labour, and external
   labour. A cheaper unit price that doubles operator hours is not a saving.
5. **Utilization** — provisioned and used per capacity metric, with the
   observation that supports it.
6. **Uncertainty** — `low`, `medium`, or `high`, with the reasons written out.
7. **Service-level constraints** — what the option must still satisfy.
8. **Failure domains** — the evaluator reports which the alternative removes and
   which it newly introduces.
9. **Exit path** — how to leave the option. An option with no known exit path is
   blocked, not merely riskier.
10. **Expected payback** — computed, never asserted.

### Unknowns are first-class

Any unknown cost, utilization, or exit path is `null`, and each blocking gap is
named in the option's `unknowns` list with the repository or authority that owns
it. The evaluator is fail-closed: one unknown makes the affected comparison
`blocked_on_evidence` rather than optimistic. A case that cannot conclude is a
valid, useful output — it names exactly what evidence would unblock it.

### Verdicts

| Verdict | Meaning |
|---|---|
| `blocked_on_evidence` | A required decision field is unknown. No recommendation. |
| `recommend` | Fully costed and saves more than EUR 5 per month. |
| `no_material_change` | Fully costed, difference within EUR 5 per month. |
| `reject` | Fully costed and more expensive than the baseline. |

`reject` is a cost verdict only. An option that costs more may still be right —
the three-node cluster case buys availability, not savings — and that argument
belongs in `decision.rationale`, made by the deciding authority against a
declared service objective, not by the calculator.

### Decision states

`blocked_on_evidence` → `proposed` → `approved` | `rejected` → `superseded`.

The evaluator enforces the transitions it can check: a case cannot be `proposed`
while any comparison is blocked, cannot be `approved` while blocked, and cannot
be decided without a named `approver` and `approved_on`.

## Cadence

| Rhythm | Trigger | Scope |
|---|---|---|
| Monthly | `cadence` | Review variance from `tools/control_cycle.py`. Open a case where forecast error is attributed to demand, price, or allocation rather than data quality. |
| Quarterly | `cadence` | Re-run every open case against refreshed evidence. Recompute all provider comparisons; a stale price is not evidence. |
| Pre-renewal | `renewal` | Open at least 60 days before `lifecycle.renews_on` or `cancel_by`, whichever is earlier, so cancellation stays possible. |
| On variance | `variance` | Sustained variance beyond the thresholds in `docs/forecast-actual-control.md`. |
| On demand | `request`, `procurement`, `incident` | A workload repository, a procurement decision, or an incident that exposed a failure domain. |

## Closing the loop

An approved case is not finished when it is approved.

1. `financial_handoff` carries the cost attribution key and the reference to
   `fin-hub` under the contract in `docs/fin-hub-resource-control-contract-v0.1.md`.
2. `decision.delegated_to` names the repositories that implement. Implementation
   detail is theirs; this repository states the interface and the acceptance
   evidence only.
3. `outcome.feeds_forecast` names the control-cycle forecast records the decision
   changes. The original forecast is never overwritten — a decision produces a
   revision, per `docs/forecast-actual-control.md`.
4. `outcome.actual_refs` collects the monthly actuals that later show whether the
   predicted saving materialised. A case whose actuals never arrive is an
   unverified case, and the next quarterly review should say so.

## Current cases

| Case | Type | State | Why |
|---|---|---|---|
| `opt:platform-audit-storage:2026-08` | `provider_switch` | `blocked_on_evidence` | Hetzner computes and is EUR 29.14 per month dearer than Scaleway at month-12 base demand, on labour rather than storage price. Host Europe has no usable price, no cancellation terms, and shares a failure domain with the host it would protect. The procurement decision itself belongs to `RESOURCE-WP-0002-T03`. |
| `opt:reef-railiance-k3s:2026-08` | `rightsizing` | `blocked_on_evidence` | Observed utilization is 14 percent CPU and 37 percent memory — a real signal from one sample. Nothing can be costed while the railiance01 booked price is unknown, so no payback exists. Blocked against `RAIL-HO-WP-0008` and `RAIL-BS-WP-0014`. |