OutlineDriven Extremely optimize
Contract
| Field | Bound contract |
|---|---|
| Trigger | Subsystem or repo-wide performance campaign against a measured floor; the user says "make this as fast as possible", "extremely optimize", or "grill every inefficiency" |
| Authority | Reversible local: writes only VCS-tracked source targets (destructive; the exact set shown before mutation); rollback is version control. No remote mutation. |
| Side effect | Hot-path source targets rewritten as atomic commits; non-wins reverted; boundary surfaces gated before any touch |
| Done | Hot units rebuilt with an even win, cold units graded fixed/at-floor/left, residue gone, verifier green, target landed atomically |
Inputs
- A named subsystem path, or no path for a repo-wide survey. Repo-wide work is opt-in and never inferred. A bare invocation profiles the repo's own workload, then works the ranked list.
- One runnable workload command exercising the target with representative input and taking at least one second of wall clock. Must be supplied or constructed before measurement begins.
- The repo's own verifier command. Must be supplied or discovered before any target lands.
Procedure
Pin the workload and baseline. Run
hyperfine --warmup 3 --min-runs 10 '<cmd>'. Record median, stddev, min, max. Reject the measurement while stddev exceeds 20 % of median: pin CPU frequency, isolate the process, widen--min-runs, or enlarge the input until the noise clears. Use this number for every later comparison. Done when: a stable baseline median is recorded with stddev under 20 % of median.Split hot from cold. Profile the workload. A unit is hot when it holds ≥ 5 % of total measured time or its call count scales with input size; everything else is cold. Write both lists down. Where a sampling profiler disagrees with a call-count argument, believe the call count and confirm by instrumentation. Done when: both hot and cold lists are written down.
State the contract, compute the 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 2× of its floor is finished: record it and move on. Done when: every hot unit has its contract stated, floor computed, and headroom multiple recorded; units within 2× of floor are marked finished.Classify the surface, then derive blind. Inventory the unit's consumers and mark each 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, plugin point). Treat consumer channels that static analysis cannot resolve, reflection, string dispatch, generated code, external integration, as boundaries until evidence changes the classification. Build the replacement from the contract and the 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, one pass where there were three, then write the code that layout implies. Done when: every consumer is classified interior or boundary, and the replacement is written from the contract and floor alone.
Audit the divergence. Walk the old implementation branch by branch and classify every behavior: folded into the replacement (essential) or cut (residue), each with a one-line reason. Read for behavior, guards, early returns, side effects, ordering guarantees, error semantics, state transitions. A branch never read is a feature deleted by accident; this walk is the only backstop. Done when: every old-implementation branch is classified as essential or residue with a one-line reason.
Gate the boundary. Present every surface marked boundary in step 4 and get an explicit answer before touching it. Interior surfaces need no ask; demolish them. Do not cut a boundary on silence or after a no. Done when: every boundary surface has an explicit answer before any touch; interior surfaces are demolished.
Measure, prove, land. Re-run the step 1 workload. A replacement that fails to beat the baseline median by 1.05× is not a win: revert it and keep the original. Run the repo's verifier, and cover every behavior classified essential in step 5 that no test reached. Delete the old unit and every symbol reachable only from it. Commit this target atomically before starting the next. Done when: the replacement beats the baseline by ≥ 1.05×, the verifier is green, essential behaviors are covered, the old unit is deleted, and the target is committed atomically.
Grill the 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 IO and repeated round-trips, startup and build cost, artifact size and dependency weight. Every unit on the cold list takes one verdict: fixed (naming the cost that fell), at floor, or left (with the reason). A cold fix that adds a branch, a cache, or a configuration knob to buy microseconds is rejected. Done when: every cold unit has a verdict (fixed, at-floor, or left with reason).
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.
Failure and recovery
| Code | Class and recovery |
|---|---|
| 10 | No workload: the target's cost cannot be reproduced on demand. Blocked: construct a runnable workload or stop. |
| 11 | Baseline too noisy: stddev exceeded 20 % of median and could not be cleared. Blocked: clear the noise or stop. |
| 12 | No headroom: every hot unit already sits within 2× of its floor. Terminal: nothing to rebuild. |
| 13 | No win: the replacement failed to beat the baseline by 1.05×. Recovery: revert the replacement, keep the original. |
| 14 | Divergence unclassified: old behavior neither folded in as essential nor cut as residue. Blocked: complete the step 5 walk. |
| 15 | Boundary cut without an answer: a published surface was destroyed on silence or after a no. Recovery: restore it and settle the question. |
| 16 | Campaign stalled mid-target: a target is half old, half new. Recovery: finish it or revert it; never ship it. |
| 17 | Scope exceeded: a repo-wide sweep ran off a named target. Recovery: revert the untargeted work. |
Partial-result rule: a target that has not reached the done predicate is reverted to its pre-campaign state; no half-rebuilt target is left in the tree. Non-mutation rule: non-wins are reverted; untargeted work is reverted. Never swallow an error or pretend the done predicate holds.
Output
Exit code 0: hot units rebuilt against their floors with a proven win (≥ 1.05× over baseline), cold units each carrying a fixed / at-floor / left verdict, residue symbols returning nothing, verifier green, each target on its own commit. Any non-zero exit code above is a terminal classification with the specific blocker named.