---
name: optimize
description: "Benchmark and optimize code across performance, memory, startup, I/O, network, concurrency, algorithmic, caching, config categories, plus meta-level: doing less, mechanical sympathy, architecture fixes."
disable-model-invocation: true
---

# Optimize

**Target**: $ARGUMENTS

## Methodology

1. **Profile** → find hotspots with canonical profiler for runtime+OS. tracing/wall-time fallback OK.
2. **Choose measurement** → match tool to scope:
   - in-process → microbenchmark
   - CLI/process → end-to-end timing
   - CPU → CPU profiler
   - memory/alloc → heap profiler
   - I/O/network → tracing
3. **Baseline** → repeatable benchmark before changes.
4. **Analyze** → connect measurements to code. explain bottleneck.
5. **Optimize** → change only measured bottlenecks.
6. **Verify** → re-run baseline/candidate. statistical comparison. report variance, significance, regressions.
7. **Document** → record methodology + rationale for non-obvious optimizations.

## Benchmarking Rigor

- **warmup** → run before measurement; discard. stabilizes JIT, caches, branch predictors.
- **outliers** → detect and remove. use IQR or MAD; report removed count.
- **effect size + confidence intervals** → report magnitude and interval, not just p-values. statistical significance ≠ practical significance.
- **repetition** → count based on variance source: between-build > between-execution > between-iteration. more reps for noisier sources.
- **isolation** → control environment: disable auto-updates, pin CPU frequency, avoid concurrent load.

## Categories

- performance / hot paths
- memory / allocations / reclamation
- startup / cold-start / init cost
- I/O / disk / syscalls / buffering
- network / requests / caching / retries
- concurrency / locks / worker pools
- algorithmic / complexity / data structures
- caching / memoization / invalidation
- config / build / deps / compiler flags

multiple categories? prioritize by impact + measurability.

## Meta

- **doing less** → same goal, fewer instructions. [ref](references/doing-less.md)
- **mechanical sympathy** → substrate awareness (runtime, VM, CPU, network, API). structure data + instructions efficiently. includes data-oriented design. [ref](references/mechanical-sympathy.md)
- **architecture** → system-level design wrong? serial vs batched, coupling, sync vs async. [ref](references/architecture.md)

## Anti-Patterns

common mistakes spanning all categories. review before profiling. [ref](references/anti-patterns.md)

## References

- [anti-patterns](references/anti-patterns.md)
- [memory](references/memory.md)
- [startup](references/startup.md)
- [io](references/io.md)
- [network](references/network.md)
- [concurrency](references/concurrency.md)
- [algorithmic](references/algorithmic.md)
- [caching](references/caching.md)
- [config-build](references/config-build.md)
- [doing-less](references/doing-less.md)
- [mechanical-sympathy](references/mechanical-sympathy.md)
- [architecture](references/architecture.md)

## Tooling

tool choice = part of the work. no hardcoded profiler/benchmark/comparison tool.
prefer canonical tools available for runtime+OS+repo. prefer existing repo automation.

missing tooling? stop. say exactly which tool + why. ask to install/enable. no silent substitution. no dep/system/build changes without approval.

## Testing

run tests. untested code → write tests first. system/dep/build changes → report.