Optimize

---
name: optimize
description: 'Use when asked to optimize code, make a path faster, make this as fast as possible, reduce allocations, repair a regression, profile a target, grill every inefficiency, or run a subsystem or repo-wide performance campaign against a measured floor; when a performance requirement, slowness report, Core Web Vitals miss, or profiling evidence identifies a bottleneck; or for an "extremely optimize" performance campaign, optimizing suspected hot paths without waiting for benchmarks, or estimating hot and complexity-neutral cold paths while refusing complexity theater. Not for remote, credential, publish, deploy, or irreversible changes.'
---

# Optimize

Five mode names share one authority: reversible local writes to the resolved target, never push, tag, publish, deploy, or mutate a remote. Full and `extremely-optimize` intentionally select the same measured-floor campaign route, rather than separate procedures; the retired name remains an explicit compatibility mode value. That route runs an isolated five-lens search with an integrated 1.05x gate and an atomic commit. Quick mode runs a single measure-identify-fix-verify loop with a noise-aware keep/revert and a CI guard for the obvious-bottleneck case. `fastopt` mode reports suspected-hot-path hypotheses without mutating code. `fastopt-extreme` mode reports estimated hot paths and complexity-neutral cold-path simplifications while refusing complexity theater.

## Contract

| Field | Bound contract |
|---|---|
| Trigger | The user asks to optimize code, make a path faster, make this as fast as possible, reduce allocations, fix a performance regression, profile and optimize a path, symbol, or diff, or a performance requirement, slowness report, Core Web Vitals miss, or profiling evidence identifies a bottleneck; asks for a measured-floor campaign, hypothesis-only suspected-hot-path analysis, or estimated hot/cold analysis that refuses complexity theater; or says "extremely optimize" or "grill every inefficiency". |
| Authority | Full and `extremely-optimize` modes write only the exact VCS-tracked source-target set shown before mutation plus `.outline/optimize/<target>/` (destructive; rollback is version control); quick mode writes only the named target and an authorized CI performance-budget or field-monitor guard; `fastopt` and `fastopt-extreme` modes are read-only with no file, VCS, credential, paid, published, deployed, or remote mutation. Full mode may commit one winning optimization, but no mode tags, publishes, deploys, or mutates a remote. |
| Side effect | Full and `extremely-optimize` modes append measurements and decisions to `.outline/optimize/<target>/log.jsonl`, benchmark isolated candidates, gate all boundary surfaces before touch, revert non-wins, apply the winner, and create one atomic commit. Quick mode applies one targeted fix and may add a CI performance budget or field monitor. `fastopt` mode emits labeled hypotheses and benchmark designs. `fastopt-extreme` mode emits hot-path hypotheses, benchmark designs, cold-path simplifications, and complexity-theater refusals. |
| Done | Full and `extremely-optimize` modes rebuild hot units with a measured 1.05x-or-better win, grade cold units fixed/at-floor/left, remove residue, pass the verifier, and land the target atomically. Quick mode: the identified bottleneck is measurably improved past noise, tests remain green, no new regressions exist, and a CI budget or field monitor guards the metric. `fastopt` mode: every named path has a labeled hypothesis and benchmark design, with no mutation or speed claim. `fastopt-extreme` mode: every hot estimate has a falsifiable benchmark, every cold candidate is complexity-neutral or rejected, and every complexity-theater proposal is refused. |
| Inputs | The required mode-specific inputs are listed below; the `mode` input selects exactly one route and must not combine a mutating route with a read-only route. |

## Inputs

- Mode (optional, exact values when supplied): `full`, `extremely-optimize`, `quick`, `fastopt`, or `fastopt-extreme`. The mode selects exactly one route; do not combine a mutating route with a read-only route. When omitted, select from the trigger and evidence.
- Full or `extremely-optimize` mode (measured-floor campaign): a named resolvable path, symbol, diff, or active local change, or no path only for an explicit repo-wide survey; repo-wide work is opt-in and never inferred. For a bare `extremely-optimize` invocation after that opt-in, profile the repository's own workload and work the ranked list. One representative runnable workload or benchmark command and repository-native verification commands are required. The workload must be supplied or constructed before measurement and must exercise the target for at least one second of wall time. The verifier must be supplied or discovered before any target lands. A supplied profile or named hotspot is optional. Optional controls are a performance budget, maximum gate attempts, maximum wall time, and minimum marginal speedup. An observable approximation is permitted only when the user's request authorizes it and the exact changed contract is confirmed before mutation. If the target or workload cannot be resolved without guessing, stop with exit 11.
- Quick mode: a resolvable target, a performance symptom and the codebase under optimization, and repository-native verification commands. Existing measurements, profiling evidence, performance budgets, or Core Web Vitals targets are optional.
- `fastopt` mode: one or more suspected hot paths named by the user (file, function, or call site) and the workload or input shape that makes each path hot. Prior measurements, profiling traces, and environment constraints are optional; absent measurements are unmeasured, not evidence of slowness.
- `fastopt-extreme` mode: the target code region or module. Call frequencies, profiling data, or prior benchmark results are optional. If no code is supplied, request the target before proceeding.

## Mode selection

| User says or evidence | Mode | Gate |
|---|---|---|
| optimize this path, profile and optimize, reduce allocations, fix a regression, hot-path speedup, make this as fast as possible, grill every inefficiency, or run a measured-floor campaign | full / `extremely-optimize` | Integrated benchmark proves at least 1.05x; adversarial behavior gate; atomic commit |
| quick optimize, obvious bottleneck, Web Vitals miss, slowness report, or single targeted fix | quick | Improvement past measurement noise; tests green; CI guard added |
| analyze suspected hot paths without waiting for benchmarks, or name a suspected hot path and its workload | `fastopt` | Read-only hypotheses and seven-part benchmark designs; no mutation or speed claim |
| estimate hot paths, simplify complexity-neutral cold paths, or refuse complexity theater | `fastopt-extreme` | Labeled hot hypotheses with falsifiable benchmarks; cold simplifications or explicit refusals; no mutation |

When the user names a hot path and a benchmark, use full mode. When the user names a single symptom and an evident bottleneck (N+1 query, missing index, bundle size, re-renders), use quick mode. When the evidence is a profiling trace with one dominant hotspot at least 5% of total time, use full mode; when one evident fix addresses the symptom, use quick mode. Use `fastopt` when the path is suspected but measurement is intentionally deferred. Use `fastopt-extreme` when only call frequency, loop depth, allocation density, or I/O and syscall evidence is available and the request rejects complexity theater. `extremely-optimize` is the explicit name for the measured-floor full route.

## Procedure

Run exactly one named mode below. Every mode is part of this single procedure; do not combine a mutating mode with a read-only mode.

### Full mode, `extremely-optimize`: measured-floor campaign

1. **Resolve the target set and bound the write surface.** Resolve one target and bound writes to that target plus `.outline/optimize/<target>/`. Record the exact VCS-tracked source-target set before mutation; generated files and untracked targets are not silently included. For an explicit repo-wide survey with no path, profile the repository workload, rank the targets, and select one target before candidate work; never infer repo-wide scope. Reject architecture-wide redesign and mixed optimization concerns. For a single function under 50 lines with one evident concern, report `auto-skip` and use one candidate; otherwise use all five lenses below. Require the runnable workload and repository-native verifier before measurement. If no workload can exercise the target, classify the run as no workload and stop. Done when: one target, its exact source set, workload, and verifier are resolved and bounded, or an explicit repo-wide survey has produced a ranked list and selected target, or `auto-skip` is reported.
2. **Pin the workload and baseline.** Run `hyperfine --warmup 3 --min-runs 10 '<cmd>'` and one suitable profiler pass. Record median, standard deviation, minimum, and maximum. Reject the measurement while standard deviation exceeds 20% of the median: pin CPU frequency, isolate the process, widen `--min-runs`, or enlarge the input until the noise clears. Record the top self-time function or widest plateau as `HOT_PATH`. If no path accounts for at least 5% of total time, continue only when call-count evidence identifies a unit whose calls scale with input and instrumentation confirms it; otherwise stop because the workload is not measurable. Done when: the workload runs for at least one second, a stable baseline with standard deviation under 20% of median is recorded, and either `HOT_PATH` is at or above 5% or a scaled-call hot unit is confirmed, or the run is stopped with its blocker.
3. **Split hot from cold.** Use the profiler pass from step 2 and write both lists. A unit is **hot** when it holds at least 5% of total measured time or its call count scales with input size; everything else is **cold**. Where the sampling profiler disagrees with a call-count argument, believe the call count and confirm by instrumentation. Done when: every relevant unit is on exactly one written hot or cold list.
4. **State each contract and compute its floor.** Work the hot list in descending order of time share. For each unit, write what it owes its callers based on call sites, tests, and the signature, never its own internals. Compute the floor from that contract alone: bytes that must move at achievable bandwidth, the algorithmic lower bound at a measured per-operation cost, and syscalls or round-trips the protocol cannot avoid. Show the arithmetic with `eval`, never in prose. Divide measured cost by floor; that multiple is the unit's headroom. A unit already within 2x of its floor is finished and moves on. Done when: every hot unit has its contract, floor arithmetic, headroom multiple, and within-2x verdict recorded.
5. **Classify consumers and derive blind.** Inventory each unit's consumers and mark it **interior** (every caller in-tree, nothing persisted or shipped) or **boundary** (public API, wire or on-disk format, config running in someone else's deployment, or plugin point). Treat reflection, string dispatch, generated code, external integration, and other channels static analysis cannot resolve as boundaries until evidence changes the classification. Build the replacement from the contract and floor alone, without reading the old implementation for structure; reading it reproduces the costly shape. Choose the data layout that puts the floor in reach: contiguity, batching, hot and cold fields split, or one pass where there were three. Done when: every consumer is classified and the replacement is written from the contract and floor alone.
6. **Audit the divergence.** Walk the old implementation branch by branch and classify every behavior as folded into the replacement (**essential**) or cut (**residue**), with a one-line reason. Read for guards, early returns, side effects, ordering guarantees, error semantics, and state transitions. A branch never read is a feature deleted by accident. Done when: every old-implementation branch is classified as essential or residue.
7. **Gate boundaries before mutation.** Present every surface marked boundary in step 5 and get an explicit answer before touching it. Interior surfaces need no ask and may be demolished. Do not cut a boundary on silence or after a no. Done when: every boundary surface has an explicit answer before any touch and all interior surfaces are demolished.
8. **Locate the benchmark evidence.** Locate or create a minimal benchmark under `.outline/optimize/<target>/`. Use the already captured step 2 workload and baseline; do not run a second baseline. Append the baseline statistics and benchmark command to `log.jsonl`. Do not continue while standard deviation exceeds 20% of the median. Done when: the existing baseline evidence and command are appended to `log.jsonl`.
9. **Start an append-only run record.** Before candidate work, append an `in-progress` record containing a run ID, target, start time, stop limits, and a fingerprint of the target revision, hot-path source, and benchmark command. Never rewrite or truncate the log. On interruption, resume only when the fingerprint matches and a fresh baseline agrees with the recorded baseline; otherwise mark measurements stale and start a new run. Reuse matching recorded candidates and rerun only missing candidates. Done when: the in-progress record and fingerprint are appended.
10. **Launch disjoint candidates.** Unless `auto-skip` applies, launch five independent, worktree-isolated candidates together. Give each the same hot-path source, benchmark, and baseline, but one distinct lens: `algo` changes complexity or removes work; `data` changes representation or layout; `cache` reuses valid results with explicit invalidation and bounds; `concur` changes safe parallelism or contention; `arch` removes a local boundary or transfer cost without redesigning the module. State that the lenses are disjoint, worktrees are isolated, and candidates become read-only after reporting. Done when: five isolated candidates are launched, or `auto-skip` uses one candidate.
11. **Measure and record each candidate.** Require each candidate to apply one transformation and run the same benchmark protocol. Return its lens, change summary, before and after medians, speedup ratio, behavior assessment, readability cost, and patch. Append each candidate record before scoring it. Do not record a failed candidate, so a resumed run retries it. Done when: every viable candidate result is appended before scoring.
12. **Score and rank.** Drop failed results and score each remaining candidate as `speedup_ratio * behavior_safety * (1 - readability_cost * 0.3)`, where exact behavior is `1.0`, a confirmed approximation is `0.7`, and unsafe or undisclosed behavior is `0.0`. Treat an approximation as viable only when the user's inputs authorize it and the changed contract is confirmed; otherwise stop with exit 14. Rank the winner and runner-up and append the ranking. Stop if no candidate reaches 1.05x. Done when: candidates are scored, ranked, and appended, or a terminal no-candidate or unconfirmed-approximation result is recorded.
13. **Run the adversarial behavior gate.** For the leading candidate, compare original and optimized behavior over output identity, error semantics, public contracts, empty and boundary inputs, negative values, NaN where applicable, and concurrent call sequences. Append every gate verdict and failure scenario. On failure, discard that candidate and consider the next ranked candidate. Done when: the leading candidate passes every adversarial gate with verdicts appended, or all candidates are discarded.
14. **Enforce promotion limits.** Before each promotion, enforce the configured maximum attempts, maximum wall time, and minimum marginal-speedup floor; default maximum attempts to the viable-candidate count and the marginal floor to 1.02. If a limit trips before any candidate passes, append the best-so-far and commit nothing. If candidates are exhausted, stop with the precise terminal class. Done when: a candidate is promoted within all limits, or promotion stops with the limit or exhaustion recorded.
15. **Measure, prove, and promote only a win.** Apply only the gate-cleared patch to the main worktree. Run the same step 2 workload with three warmups and at least ten measured runs, append the integrated median, variance, and speedup, and discard the target patch if `baseline_median / integrated_median < 1.05`. Run the repository's verifier and cover every essential behavior from step 6 that no test reached. Done when: the integrated benchmark proves at least 1.05x speedup and all required behavior is covered, or the target is restored with the blocker recorded.
16. **Land one concern.** Delete the old unit and every symbol reachable only from it. Commit exactly the named target as one optimization concern. Include the hot path, lens, rationale, baseline and integrated medians with variance, ratio, and any confirmed approximation contract in the commit message. Remove only `.outline/optimize/<target>/agent-*` worktrees, preserve the log and benchmark evidence, and append the authoritative terminal `run` record with status `done` and exit 0. Done when: one atomic optimization commit is made, residue symbols return nothing, candidate worktrees are removed, and the terminal run record is appended.
17. **Grill cold paths.** Cold code is off the clock; buying speed with complexity is a loss. Hunt waste that costs something other than time on this workload: complexity that bites at a larger N, allocations and retained memory, redundant I/O and repeated round-trips, startup and build cost, artifact size, and dependency weight. Every unit on the cold list takes one verdict: **fixed** (name the cost that fell), **at floor**, or **left** (with the reason). A cold fix that adds a branch, cache, or configuration knob to buy microseconds is rejected. Done when: every cold unit has a fixed, at-floor, or left verdict.

Work one target at a time. Half-rebuilt is the forbidden state: finish a target or revert it. Scope equals the ask; never escalate a named target into a repo-wide campaign.

### Quick mode

1. **Establish baseline.** Measure the bottleneck with profiling tools or timing data before touching any code. Record the specific metric, the tool or method used, and the measured value. If a baseline cannot be established, stop and report blocked. Done when: the metric, tool, and measured value are recorded.
2. **Identify the specific bottleneck.** Use the symptom to determine the profiling target: frontend performance (Lighthouse, DevTools Performance tab, web-vitals RUM), backend latency (APM, query logging, EXPLAIN ANALYZE), bundle analysis, or heap profiling. Do not assume the cause. The query plan is the measurement for database queries; the trace is the measurement for frontend jank. Done when: the profiling target is determined from the symptom.
3. **Fix the identified bottleneck only.** Apply one targeted change. Code it completely before measuring again. Common fixes: N+1 queries -> single query with join or include; unbounded pagination -> limit and offset; missing index -> `CREATE INDEX` with a composite key shaped to the query; connection pool exhaustion -> size the pool to the database ceiling; large bundle -> code splitting or lazy loading; unoptimized images -> responsive `srcset`, lazy loading, or a modern format; unnecessary re-renders -> `React.memo`, `useMemo`, or stable references; missing caching -> cache expensive reads with a stated TTL and key design. Done when: one targeted change is coded completely.
4. **Re-measure under identical conditions.** Use the same tool, same conditions, and same measurement method as the baseline. Make one change at a time. Done when: the after-measurement is recorded under identical conditions.
5. **Keep or revert strictly.** Past noise and tests green: keep. Within noise or tests red: revert immediately. Neutral is a revert. An optimization that wins by dropping needed work is a revert. Done when: the change is kept (past noise, tests green) or reverted (noise, tests red, or neutral).
6. **Guard the metric.** Add a synthetic CI performance budget or a field monitor (RUM p75) for the primary metric. This prevents the fix from regressing unseen. Done when: a CI performance budget or field monitor guards the primary metric.

### `fastopt` mode: hypothesis-only analysis

1. **Read each named path.** For each suspected hot path, read the source and surrounding call graph read-only. Record the inputs, allocations, loops, and branches that plausibly dominate cost. Done when: every named path is read and its cost-plausible elements are recorded.
2. **Label observations as hypotheses.** For every cost observation, state the assumed workload, assumed dominant operation, and assumed magnitude rank. Label it a hypothesis, never a finding, and make no speed claim. Done when: every observation has its hypothesis label, workload, dominant operation, and magnitude rank.
3. **Design a falsifiable benchmark.** For each hypothesis, name the metric, baseline, variant, workload generator, warm-up, repetition count, and noise controls that would confirm or refute it. Done when: every hypothesis has all seven benchmark elements.
4. **Bound the implied change.** Restrict any implied change to the named path; do not propose edits outside it or assume a fix is correct. Done when: every hypothesis has a bounded change scope.
5. **Report measurement blockers.** If a hypothesis cannot be tested without mutating code, state the minimal mutation needed to measure it and stop before performing it. Done when: the blocking reason and minimal mutation are stated, or the hypothesis is testable read-only.
6. **Emit without mutation.** Emit the hypotheses and benchmark designs as chat output. Do not mutate any file and do not claim a speedup. Done when: the chat report is emitted with no mutation or speed claim.

### `fastopt-extreme` mode: estimate and complexity-neutral simplification

1. **Bound scope.** Restrict analysis to the named code region or module and do not widen to unrelated code. Done when: scope is bounded to the named region or module.
2. **Estimate hot paths.** Estimate hot paths from call frequency, loop depth, allocation density, and I/O or syscall blocking. Label every estimate as a hypothesis, not a measured fact, and state its basis. Done when: every hot-path estimate is labeled with its basis.
3. **Classify cold candidates by complexity.** Identify complexity-neutral cold paths whose optimization adds no new abstraction, wrapper, configuration flag, caching layer, or indirection. The change must be simpler than or equal in complexity to the original. Done when: every cold candidate is classified as complexity-neutral or rejected.
4. **Design hot-path benchmarks.** For each hot-path hypothesis, state the metric, baseline measurement, and falsification condition under which the hypothesis is rejected. Done when: every hot-path hypothesis has a benchmark design with its metric, baseline, and falsification condition.
5. **Propose cold simplifications.** For each complexity-neutral cold candidate, state the specific simplification and why it adds no complexity. Done when: every cold candidate has its simplification and complexity justification stated.
6. **Refuse complexity theater.** Reject any proposal that introduces a new abstraction, wrapper, flag, caching layer, or indirection whose complexity exceeds the gain it claims. State the complexity cost and claimed gain. Done when: every complexity-theater proposal is refused with its cost and claimed gain.
7. **Emit without mutation.** Emit all hypotheses, benchmark designs, simplification proposals, and refusals as chat output. Do not mutate any file. Done when: the chat report is emitted with no file mutation.

## Failure and recovery

### Full mode and `extremely-optimize`

Full and `extremely-optimize` intentionally share this measured-floor route. The exit map below is canonical for both names, rather than maintaining two procedures or two conflicting code maps.

| Terminal class | Recovery |
|---|---|
| No workload (exit 10) | The target's cost cannot be reproduced on demand. Construct a runnable workload or stop; do not claim success. |
| Baseline too noisy (exit 11) | Standard deviation exceeds 20% of median and cannot be cleared. Clear the noise or stop. |
| No measurable hotspot (exit 11) | No path accounts for at least 5% of time or the workload is not measurable. Report the blocker and commit nothing. |
| No headroom (exit 12) | Every hot unit is already within 2x of its floor. Report the terminal result and commit nothing. |
| No candidate or integrated no-win (exit 13) | No candidate or integrated result clears the 1.05x gate. Revert the replacement or target patch and keep the original. |
| No win or failed behavior/check gate (exit 13) | A candidate fails the campaign gate, or the repository checks fail. Revert the replacement or target patch and keep the original. |
| Approximation unconfirmed (exit 14) | The request did not authorize the approximation or the changed contract was not confirmed. Discard that candidate and do not promote it. |
| Divergence unclassified (exit 14) | Old behavior is neither folded in as essential nor cut as residue. Complete the step 6 walk before proceeding. |
| Mixed optimization concerns (exit 15) | The proposed commit mixes concerns and must be split before retrying. |
| Boundary cut without an answer (exit 15) | A published surface was destroyed on silence or after a no. Restore it and settle the question. |
| Campaign stalled mid-target (exit 16) | A target is half old and half new. Finish it or revert it; never ship it. |
| Scope exceeded (exit 17) | A repo-wide sweep ran off a named target. Revert the untargeted work. |
| Stopping limit (exit 16) or failed verifier (exit 13) | Before commit, restore only the named target and remove only run-created candidate worktrees; retain append-only evidence, append the exact terminal class, commit nothing, and never revert an unrelated commit. Resume only through the fingerprint match and fresh-baseline agreement. |

Partial-result rule for full and `extremely-optimize`: a target that has not reached the done predicate is reverted to its pre-campaign state; no half-rebuilt target remains. Non-wins and untargeted work are reverted. Never swallow an error or pretend the done predicate holds.

### Quick mode

| Failure | Response |
|---|---|
| Baseline unavailable | Measurement tools are unavailable or the codebase cannot be profiled. Result: blocked. Do not proceed without baseline evidence. |
| No bottleneck found | Profiling reveals no measurable code-level bottleneck. Report uncertainty and whether environmental or statistical noise is suspected. |
| Fix produces no measurable gain | Improvement is within noise range of the baseline. Revert. Never keep a neutral change. |
| Correctness regression | Tests fail or behavior changes after the fix. Revert immediately. Correctness gates the metric. |
| Fix exceeds available authority | The bottleneck requires unavailable credentials, remote mutation, or infrastructure changes outside local write scope. Document the requirement and do not widen authority. |

Partial-result rule for quick mode: reverted code leaves no trace. Keep a ledger entry (baseline, fix applied, before/after measurement, and verdict) so discarded ideas are not re-profiled.

### `fastopt`

| Failure | Response |
|---|---|
| Unmeasured path | Mark the hypothesis unmeasured; do not infer slowness from absent data. |
| Ambiguous hot path | Ask the user to name the path and workload; stop rather than guess. |
| Benchmark infeasible read-only | State the blocking reason and the minimal mutation that would unblock measurement; do not perform it. |
| No recovery widens authority | `fastopt` never mutates files, VCS, credentials, or remote state; a blocked result is emitted as blocked, not as success. |

### `fastopt-extreme`

| Failure | Response |
|---|---|
| No code supplied | Request the target code region or module; do not guess or analyze from memory. |
| Path unclassifiable | Label a path unclassified and exclude it from optimization proposals. |
| Complexity theater detected | Refuse the proposal and record its complexity cost and claimed gain. Do not emit it as a valid optimization. |
| Partial result | Emit obtained hypotheses and designs, and mark every unclassified or refused item so the done predicate is not falsely satisfied. |
| Non-mutation | No file, VCS, or remote change is made. Rollback is not applicable. |

## Output

**Full mode and `extremely-optimize`.** On success, return exit 0 with the commit identifier, target, selected lens, benchmark command, baseline and integrated statistics, measured speedup, behavior-gate result, repository checks, cold-path verdicts, and durable log path. On failure, return the applicable terminal class, unchanged or rolled-back target state, measurements obtained, and the precise blocker; never report a worktree-only result as a landed win.

**Quick mode.** Return optimized code with before/after measurements, plus a ledger entry per attempt (kept and reverted) documenting the hypothesis, baseline, result, and verdict. Each entry states the metric name, baseline value, result value, and tool used.

**`fastopt` mode.** Return one labeled hypothesis per suspected path and one benchmark design per hypothesis containing the metric, baseline, variant, workload generator, warm-up, repetitions, and noise controls. Report blocked paths with their reason and minimal measurement mutation. Never mutate or claim a speedup.

**`fastopt-extreme` mode.** Return hot-path hypotheses with falsifiable benchmark designs, complexity-neutral cold-path simplification proposals, and explicit complexity-theater refusals with their complexity costs and claimed gains. Never mutate a file.