git:20260714.061716b to git:20260714.4fd0952

+ ---

+ name: Optimization

+ description: >

+ Measure-first performance optimization playbook — profiling discipline, bottleneck

+ triage (CPU/memory/I/O), caching layers, and the algorithm/DB/frontend/network fix

+ patterns. Use when the user reports something is slow ("dashboard takes forever",

+ "API is laggy", "bundle is 2MB", "memory keeps growing"), asks to profile,

+ benchmark, reduce latency/bundle-size, or fix N+1 queries — and to interpret the

+ output of the /forge:optimize command or the `performance` agent.

+ when_to_use: >

+ Triggers: "it's slow", "profile this", "reduce bundle size", "optimize this query",

+ "memory leak", "N+1 queries", "improve response time", "benchmark", "the app lags",

+ "cut load time", "why is this taking so long". Also when reviewing /forge:optimize

+ output or briefing the `performance` agent (agents/performance.md).

+ user-invocable: false

+ allowed-tools: Read, Grep, Glob, Bash

+ ---

+

+ # Performance 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](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](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.

+