---
name: Rig Optimize
description: Improve a measured performance metric in guarded rounds, keeping only changes that beat the baseline noise and pass every correctness gate.
---

# Rig Optimize

> Read [Evidence rules](../../references/evidence.md).

> This workflow changes code, one measured variable at a time. It never commits, pushes, or rewrites history; a human or `rig-implement` owns the commit.

## Preconditions

- The benchmark is an already-configured gate. Detect it with `rig_gate` and `action: "detect"`.
- The benchmark prints a stable metric and exits non-zero on failure.
- There is no benchmark gate? Stop and ask the user to configure one. Never invent an ad-hoc benchmark command, and never use a paid or network-dependent benchmark without explicit approval.

## Workflow

1. **Declare the contract.** Metric, unit, direction (lower or higher is better), target, minimum improvement (default 5%), rounds budget (default 3), and the exact gate id. Start the run with `rig_evidence` and bind the benchmark script and fixtures as `inputs`.
2. **Measure the baseline.** Run the benchmark gate at least three times from a clean start. Record every receipt, the median, the spread, and the environment (hardware, runtime version, cache state). Statistical noise is evidence, not an obstacle.
3. **Profile before editing.** Use the project's profiler or timing instrumentation to name the hotspot. Profile output is an `output`, not a claim.
4. **Change one variable.** State the hypothesis, the expected effect, the files to touch, and the rollback. Do not combine a refactor with a measurement round.
5. **Re-measure the same way.** Rerun the benchmark gate at least three times under the same conditions. A win must exceed the baseline spread and the declared minimum improvement. Also run every non-benchmark gate: a faster build that breaks correctness is a regression.
6. **Decide and record.** Keep the round when it wins and everything passes; otherwise restore the touched files exactly and record the failed hypothesis with `rig_evidence` `action: "record"` and a `decision`. Never rewrite or delete the measurement history.
7. **Stop honestly.** Stop on target reached, improvement below noise after the round budget, a correctness regression, or an exhausted budget. A non-improvement is a valid result.
8. **Review independently.** Dispatch `rig-optimizer` to check the methodology: sample count, variance, warmup, environment, and whether the benchmark still measures the intended behavior. Record it with `reviewer`.
9. **Finalize.** `rig_gate` for the full set, then `rig_evidence` with `action: "finalize"`.

## Rules

- Never change the benchmark, its fixtures, or its inputs in a round that claims a win. A benchmark change is its own round with its own baseline.
- Never skip a correctness gate because the benchmark passed.
- Never claim an improvement from a single run, from an unmeasured change, or from a different machine.
- Never upgrade a dependency, change a compiler flag, or alter a fixture without explicit approval.
- Never commit, push, tag, or rewrite history in this workflow.
- If the metric is unstable across identical runs, report that first and stop; do not optimize against noise.

## Output

The metric contract, baseline median and spread, per-round hypothesis and measurement, kept and reverted rounds with reasons, the final measured delta, correctness gate results, environment, limits, and the proposed commit scope for a human.