Optimization

Diagnose and fix performance problems from measurement, never from guessing. This skill is the reasoning layer; the deterministic scan lives in the /forge:optimize command and the performance agent.

The one rule

Measure → find the real bottleneck → fix that one thing → re-measure. Repeat.

Premature optimization wastes effort on code that isn't hot. A profile that shows where time/memory/allocations actually go beats any intuition. Optimize the top item, prove the delta, then re-profile — the bottleneck usually moves.

Where this fits in Forge

| Surface | What it does | When | |---|---|---| | /forge:optimize (command) | Deterministic 7-dimension static scan (large files, as any, dead exports, deps, dup, console, TODO debt) + optional --fix | Codebase-health sweep, refactor triage | | performance agent (agents/performance.md) | Bundle analysis, React render profiling, memory-leak hunting, API latency | Deep dive on a specific slow surface | | This skill | The measure-first method + fix patterns both of the above apply | Any "it's slow" reasoning |

/forge:optimize is a TypeScript-oriented static-quality scan — it does not run a profiler. For actual runtime numbers you still profile (browser DevTools, cargo flamegraph, node --prof, EXPLAIN ANALYZE). Read reference/patterns.md for the full per-domain fix catalog; keep this file for triage.

Triage: classify the bottleneck first

Before touching code, put the symptom in one bucket — the fix set is different for each.

• CPU-bound — high CPU, work scales with input. Causes: O(n²) loops, redundant recompute, heavy regex, no memoization. Fix: better algorithm/data structure, cache results, memoize.
• Memory-bound — RSS climbs, GC thrash, OOM. Causes: leaks (unremoved listeners, growing caches), giant objects held in scope, no pagination. Fix: release refs, bound caches, stream/paginate.
• I/O-bound — low CPU but slow wall-clock. Causes: sync I/O, N+1 queries, chatty network, missing cache. Fix: batch, async/parallel, cache, add indexes.

Quick discriminator: if CPU is pegged → CPU-bound; if wall-time ≫ CPU-time → I/O-bound; if it degrades over hours/requests → memory leak.

Worked example — "the dashboard takes forever to load"

1. Measure — DevTools Performance tab + Network waterfall. Observe: 1.8s blocked on a single /api/tasks call; main thread idle during it. → I/O-bound, not render.
2. Find — server logs show /api/tasks fires one query per task (N+1): 1 list + 240 detail queries.
3. Fix that one thing — replace the loop with a single joined/batched query.
4. Re-measure — call drops 1.8s → 90ms. Load now render-bound at 300ms.
5. Repeat — next profile shows a synchronous 200-row render → add virtual scrolling.

Note how the bottleneck moved after each fix. Stopping after step 3 and "also" adding a Redis cache would have optimized the wrong layer.

Worked example — "our bundle is over 2MB"

1. Measure — npx vite-bundle-visualizer (or source-map-explorer dist-ui/*.js). Observe one dependency is 60% of the bundle.
2. Fix — code-split the route that needs it (React.lazy / dynamic import()), or swap for a lighter lib; tree-shake by importing the used export only.
3. Re-measure — confirm the initial chunk shrank; verify no runtime regression with npm test.

Fix pattern index

Deep catalog with concrete code lives in reference/patterns.md:

• Algorithm — data-structure choice, complexity reduction, lazy evaluation
• Database — indexes, N+1 elimination, batching, EXPLAIN plans, partitioning
• Frontend — code splitting, lazy loading, virtual scrolling, debounce/throttle, Web Workers, requestAnimationFrame
• Network — fewer requests, compression, HTTP/2, pagination
• Caching — the 4 cache levels and 5 write/read patterns, with invalidation traps

Gotchas

• /forge:optimize grep-excludes any path containing the substring test (grep -v test). A file named contest.ts or a dir like latest/ is silently dropped from the type-safety / console / dead-code counts. Don't treat its "0 console statements" as proof — spot-check.
• Dimension 1 (large files) only matches *.ts, not *.tsx. In forge-ui (React 19) the biggest files are .tsx and won't appear in the >300-line list. Re-run the find with -name "*.tsx" for the UI repo.
• The command is TypeScript/npm-shaped. It scans src/, runs npm outdated, depcheck. It says nothing about forge-orchestrator (Rust) — there you profile with cargo flamegraph, size-optimize via the release profile (opt-level=z, LTO, stripped, already set in that repo's Cargo.toml), not depcheck.
• Caching is the #1 source of correctness bugs, not just a speed win. Every cache needs an invalidation story. Stale reads from an un-invalidated write-behind cache look like "the data is wrong", not "the app is slow" — cache last, and only after the slow path is proven and correct.
• Micro-optimizing an I/O-bound path does nothing. Hand-tuning a loop that spends 95% of wall-time waiting on the DB is wasted effort. Always confirm the bucket (CPU/memory/I/O) before choosing a fix, or you optimize the 5% that doesn't matter.
• A single benchmark number is noise. Warm up, run multiple iterations, report median/p95 — JIT, cold caches, and GC pauses make a first-run timing meaningless.
• --fix writes files. The command runs analysis read-only and presents a plan first; never let it auto-apply on an unstaged tree you can't git diff to review.

Workflow

1. Baseline — capture current numbers with a real tool (not a stopwatch feel).
2. Classify — CPU / memory / I/O bucket.
3. Profile — find the single hottest item in that bucket.
4. Fix one thing — the smallest change that removes the top item.
5. Validate — re-measure the delta; run tests so the fix didn't break behavior.
6. Repeat or stop — if the new top item is under budget, stop.

Additional resources

• reference/patterns.md — full algorithm / DB / frontend / network / caching fix catalog with code.
• commands/optimize.md — the deterministic 7-dimension scan and its --fix flow.
• agents/performance.md — the profiling/bundle/leak specialist agent.