optimize

What this skill does

# Optimize — applied hot-path transform with a proven win

A self-contained diagnose→optimize→verify loop. Locate the hot path (lightly — no full
investigation ledger), fan out five candidate transformations as worktree-isolated `Agent` calls,
benchmark each, gate on behavior, commit the winner. The deliverable is a **committed, measured
change** — not a verdict, not a report, not a list of suggestions.

Op-cell is context-dependent: `correct` + `Restores: spec:<budget>` when a `--budget` or a named
regression is the target; `compress` when removing wasted work with no stated budget; `extend` when
the winning change adds an approximation or cache contract that changes observable semantics.
Rejection grounds: **Excess** (micro-opt with no measured hotspot), **Graft** (optimization applied
before the hotspot is confirmed), **Sprawl** (added complexity that outweighs the earned speedup).

**Reference files (verbatim prompts, agent dispatch shapes, harness templates):**
- `references/lenses.md` — five lens prompts sent to candidate agents, one per lens
- `references/tooling.md` — per-language benchmark/profile tooling matrix + minimal harness
  templates for the author-a-harness phase

## Constitutional Rules (Non-Negotiable)

1. **No optimization without a measured hotspot.** Accept a supplied profile, symbol, or `perf-profile` output — or run Phase 2's light locate. Never fan out candidates against unmeasured code.
2. **Benchmark before landing.** Every accepted change carries a before/after `hyperfine --warmup 3 --min-runs 10` measurement (variance-aware). If no harness exists, author a minimal throwaway under `.outline/optimize/`. Fall back to a rigorous complexity/allocation argument only when benchmarking is genuinely impractical — label it `[UNMEASURED]` in the commit body.
3. **Behavior preservation is a gate, not a guideline.** Observable output must be identical by default. Approximation (lossy fast-path, float reassociation, bounded staleness, bounded cache eviction) is permitted only when the user explicitly requests it in prose AND the skill presents the exact contract change for confirmation before applying anything.
4. **One optimization concern per atomic commit.** Algorithmic change + data-structure swap in one commit trips exit 15; split first.
5. **Auto-skip for trivial targets.** A single function <50 LOC with an obvious single-concern win runs a single-pass optimize-and-measure, not a five-agent fleet. Name the auto-skip in the output so the user knows.

## When to Apply

- The user says "optimize this", "make X faster", "speed up the hot path in Y", "reduce allocations in Z", "fix the perf regression", "profile and optimize `<symbol>`".
- A hotspot has already been identified (perf-profile output, flamegraph, or named symbol) and the next step is transformation.
- A performance budget is stated (`--budget`) and the current code does not meet it.
- Active context (current diff/file/stack) is measurably slow and the user wants the fix landed, not analyzed.

## When NOT to Apply

- **Diagnosis with no transform authorized** — that is `perf-profile`. Use it first if the hotspot is unknown; then come back here.
- **Full investigation with a persisted ledger + keep/stop verdict** — that is `perf-investigate`. Use it when you need an auditable case file across multiple experiments.
- **Behavior-preserving entropy reduction on a diff** — that is `simplify`. It runs no benchmarks and explicitly forbids behavior-affecting speedups.
- **Unmeasured code with speculative "this might be slow"** — Graft rejection; locate the hotspot first.
- **No measurable improvement expected** — if the candidate analysis shows noise-level gains, exit 12.
- **Architecture-level redesign** — `perf-investigate` or a plain planning session. Optimization surgery within a hot path is in scope; full module rewrites are not.

## Workflow

### Phase 1 — Resolve target

If `/optimize <path|symbol|diff>` was given, use that as the target. If no arg, detect active
context (current diff, current file in editor, top of git stack) as `tidy` does — if the context is
empty or unresolvable, error explicitly rather than guessing.

**Auto-skip check:** if the resolved target is a single function <50 LOC and only one obvious
concern is visible, declare auto-skip, note it aloud, and proceed with a single-pass loop (Phases
3 → 5 single-agent → 6 → 7 → 8). Otherwise proceed with the full five-agent fan-out.

Parse `--budget <metric>` (e.g. `--budget p95<3ms`, `--budget throughput>10k/s`,
`--budget alloc<1MB`) — sets the op-cell to `correct` and the stop condition.

### Phase 2 — Locate / accept the hotspot

If a profile artifact, flamegraph, or named symbol was supplied, accept it and skip profiling.

Otherwise run a light locate:
1. `hyperfine '<workload cmd>'` — confirm the workload takes measurable wall-clock time.
2. One profiler pass at the right level (see `references/tooling.md` for per-language choice).
3. Identify the top self-time function or widest plateau. Document it as `HOT_PATH`.

If no hotspot clears a 5 % share of total time, exit 11 — no actionable target.

### Phase 3 — Establish baseline benchmark

Author or locate a benchmark harness for `HOT_PATH` (see `references/tooling.md`). If none exists,
write a minimal throwaway harness under `.outline/optimize/<target>/bench.*` that exercises the hot
function in isolation. Run:

```
hyperfine '<bench cmd>' --warmup 3 --min-runs 10 --export-json .outline/optimize/<target>/before.json
```

Record: median, stddev, min/max. This is the before measurement. **Do not proceed if stddev >
20 % of median** — fix measurement noise first (pin CPU frequency, isolate the process, widen
`--min-runs`).

### Phase 4 — Fan out candidate agents

Launch five worktree-isolated agents in **one tool-call message** (independent by construction —
disjoint lenses, no shared files). For each lens `L` in {`algo`, `data`, `cache`, `concur`,
`arch`}:

```
Agent(
  prompt  = references/lenses.md § <L> + "\n\n---\n\nHOT_PATH: " + <symbol> +
            "\n\nCODE:\n" + <hot-path source> +
            "\n\nBEFORE (hyperfine median): " + <before_median>,
  isolation = "worktree"
)
```

Each agent must:
1. Apply its transformation inside the worktree.
2. Run the harness: `hyperfine '<bench cmd>' --warmup 3 --min-runs 10 --export-json after.json`.
3. Report back a JSON result: `{lens, change_summary, before_median, after_median, speedup_ratio, behavior_self_assessment, readability_cost, diff_patch}`.

Document the independence argument in the spawn message: "disjoint lenses, isolated worktrees,
read-only phase after reporting".

### Phase 5 — Score and rank candidates

Collect the five result objects (null = agent failed; `.filter(Boolean)` before ranking). Compute:

```
composite = speedup_ratio × behavior_safety × (1 - readability_cost × 0.3)
```

Where `behavior_safety` = 1.0 (exact behavior claimed), 0.7 (approximation with disclosed
contract), or 0.0 (unsafe / undisclosed). Sort descending. Name the winner and the runner-up.

If `speedup_ratio < 1.05` for all candidates, exit 12 — no candidate clears noise.

If the winner relies on approximation (behavior_safety < 1.0) and the user has not already
confirmed in prose: present the exact contract change and wait for confirmation. If declined, exit
14. If confirmed, set op-cell to `extend` and document the contract change in the commit body.

### Phase 6 — Adversarial behavior gate

Dispatch a single adversarial reviewer agent:

```
Agent(
  prompt = "You are an adversarial reviewer. The following optimization diff was applied to <HOT_PATH>.
            Try hard to construct any input or call sequence where the optimized version produces
            a different observable result than the original. Check: output identity, error
            semantics, public API contract, edge inputs (empty, max, negative, NaN, concurrent).
            If approximation is claimed, check that the contract was disclosed corr