# Rig Optimize

> Improve a measured performance metric in guarded rounds against a configured benchmark gate, keeping only noise-clearing wins that pass correctness gates. Use for a concrete performance target. NOT for speculative refactors or unmeasured tuning.

- Skill: `borda/rig-optimize` (Agent Skill)
- Install (CLI): `npx get-skill add borda/rig-optimize`
- Raw SKILL.md: https://api.skillmd.com/api/skills/borda/rig-optimize/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Borda (https://skillmd.com/u/borda)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/borda/rig-optimize

---


# Rig Optimize

> Read [Evidence rules](../../references/evidence.md). Follow [Role dispatch](../../references/evidence.md#role-dispatch) for native-agent fallback and stop on reported scope violations.

> 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` (`action: "start"`, `skill: "rig-optimize"`, and the target paths), keep the returned `run_id`, then call `rig_evidence` with `action: "record"`, that `run_id`, and 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.** Before measuring the edited candidate, call `rig_evidence` with `action: "refresh"`, the `run_id`, and a `message` naming the candidate change. 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. If a gate rewrites source, refresh again and rerun the affected measurements and correctness checks.
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`. After every kept or reverted round, call `rig_evidence` with `action: "refresh"`, the `run_id`, and a `message` explaining the round outcome so the scope matches the retained source before review. 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` on the refreshed final scope 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.

