/optimize

name: optimize
description: Optimize a measurable metric with bounded iterations, resumable numeric campaigns, isolated ablations, and descriptive retrospectives.

> Before asking, read [User Questions](../../shared/codex-user-questions.md). Waits, plan updates, and test runs follow [Agent Waits](../../shared/native-skill-contract.md#agent-waits), [Plan Updates](../../shared/native-skill-contract.md#plan-updates), and [Sandboxed Test Runs](../../shared/native-skill-contract.md#sandboxed-test-runs).

Optimize

> Task-size routing follows [Proportional Execution](../../shared/native-skill-contract.md#proportional-execution); this skill's specialized lifecycle and acceptance checks remain authoritative.

Metric-driven optimization with explicit guards, rollback criteria, experiment log.

Input Schema

{
  "goal": "required measurable improvement objective",
  "mode": "single|campaign|resume|ablation|retrospective",
  "checkpoint": "optional boolean for a resumable numeric campaign; default false",
  "source_run": "required existing managed run directory for resume, ablation, or retrospective",
  "variants": "ablation only: bounded named component-removal patches and their rationale",
  "metric_cmd": "required for single and campaign; for resume, ablation and retrospective recovered from source_run: command that emits or validates the target metric",
  "metric_direction": "higher|lower",
  "guard_cmd": "required for single and campaign; recovered from source_run otherwise: command that must continue to pass",
  "max_iterations": "optional integer, default 1",
  "min_delta": "optional practical significance threshold",
  "scope_files": [
    "paths the optimization may edit"
  ],
  "done_when": "metric improves without guard regression"
}

For `resume`, recover goal, commands, scope, direction and total budget from `source_run`; supplied replacements must match the frozen configuration. `ablation` and `retrospective` derive measurement configuration from that source rather than requiring duplicate inputs. Existing `single` and non-checkpointed `campaign` accept numeric or pass/fail metrics unchanged. The checkpoint helper and new numerical analyses require finite numeric values; explain unsupported historical/pass/fail input instead of inventing a metric or migrating a log silently.

Mode Dispatch

• `single` or `campaign` without `checkpoint`: follow the existing workflow below.
• `campaign` with `checkpoint`, or `resume`: read [Managed campaigns](campaign.md). It wraps steps 02–07 with durable checkpoints, then returns to steps 08–09. Resume keeps the original run directory; never initialize or truncate it again.
• `ablation`: read [Component ablations](ablation.md), create a separate result run in step 01, then complete steps 08–09 with the mode's retained evidence.
• `retrospective`: read [Experiment retrospective](retrospective.md), create a separate result run in step 01, then complete steps 08–09. No source mutation or measurement execution is required.

The local [campaign.py](campaign.py) helper performs deterministic state/receipt checks and summaries, not metric execution or automatic source restoration. Invoke it through `PLUGIN_ROOT/bin/python` (native Windows: `PLUGIN_ROOT/bin/python.cmd`) and inspect `--help`. The agent owns actual command execution, measurement provenance, safe rollback, and worktree orchestration. A digest check establishes consistency, not authenticity of execution.

Workflow

01: Create run directory

Run `create_run.py --skill optimize` per `../../shared/helper-cli-contract.md`.

02: Validate metric and guard commands

Require:

• Repeatable `metric_cmd` producing comparable value or pass/fail.
• Known `metric_direction`.
• `guard_cmd` fails on unacceptable regressions.
• Bounded `scope_files`.
• Explicit, bounded `max_iterations` for `campaign`.
• Protect files/scripts used by `metric_cmd`/`guard_cmd` unless user explicitly scopes them and accepts measurement-integrity risk.

Dry-run both before edit:

Execute configured `metric_cmd` and `guard_cmd` separately with host-native command runner. Write complete combined output to `<run-directory>/metric-baseline.txt` and `<run-directory>/guard-baseline.txt`; retain both exit codes. If a missing declared project dependency prevents a command from running, apply [Project Dependency Preparation](../../shared/native-skill-contract.md#project-dependency-preparation), preserve the earlier attempts separately, and rerun both baseline commands in the resulting environment before accepting the baseline or editing source. Stop before editing while either baseline remains unavailable.

Dependency preparation changes a measurement input: invalidate earlier measurements from the previous environment, including when preparation occurs during an iteration or resume. Recapture the baseline on its original source under the owning workflow's source-state and measurement-integrity rules before comparing results. If equivalent recapture is unavailable, retain an inconclusive result with no improvement claim; never attribute an environment change to a source optimization.

03: Record baseline and hypothesis

Write `<run-directory>/hypothesis.md`:

• metric to improve
• expected mechanism
• files allowed to change
• guard risk
• rollback condition

For `campaign`, noisy metrics, GPU/ML performance, or correctness-sensitive code, read and apply `../../shared/specialist-orchestration.md`; otherwise do not load it. Write `<run-directory>/specialist-optimization-plan.md` with narrow context packs for:

• `squeezer`: profiling mechanism, bottleneck hypothesis, measurement plan.
• `qa-specialist`: guard coverage and regression risk.
• `data-steward`: data pipeline or reproducibility impact.
• `scientist`: metric validity, ablation design, statistical noise.
• `challenger`: overfitting to metric or weakening guard checks.

No fan-out for one small measured change with stable metric/guard. Never