# Perf Optimization

> Profile-driven performance optimization: methodology, pattern catalog, safety invariants, when-to-stop heuristics. Language-specific in languages/*.md.

- Skill: `irahardianto/perf-optimization-3` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx get-skill add irahardianto/perf-optimization-3`
- Raw SKILL.md: https://api.skillmd.com/api/skills/irahardianto/perf-optimization-3/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: irahardianto (https://skillmd.com/u/irahardianto)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/irahardianto/perf-optimization-3

---


# Performance Optimization Skill

## When to Use
- Profiling data available (pprof, flamegraph, py-spy, Chrome/Dart DevTools)
- User requests perf analysis
- Benchmark regression detected
- New feature touches hot path

## Methodology

Profile → Analyze → Prioritize → Optimize → Benchmark → Improvement? → Verify & Ship (or re-prioritize)

### 1: Profile
Language-appropriate tool (load `languages/*.md`). Output: raw CPU/heap/trace profile.

### 2: Analyze
1. **Focus `cum`** — total cost of fn + everything it calls. Finds expensive flows.
2. **Contextualize `flat`** — fn's own cost. Trace runtime fns (GC, malloc) UP to user code.
3. **Ignore runtime noise** — scheduler overhead always appears. Note GC pressure but don't "fix" scheduler.
4. **Separate benchmark artifacts** — test harness allocations (httptest, ResponseRecorder) aren't production cost.

Output: `docs/research_logs/{component}-perf-analysis.md`

### 3: Prioritize

| Priority | Criteria |
|---|---|
| Do first | Low risk, high impact (caching, pre-alloc, fast-reject) |
| Do second | Medium risk, high impact (library swap, algorithm change) |
| Do last | High risk, high impact (major refactor, custom impl) |
| Skip | Any risk, low impact (micro-opt below noise) |

Rule: >1 day AND <20% hot path savings → defer.

### 4: Optimize
One fix at a time. TDD (Red→Green→Refactor). Run tests. Benchmark immediately. Never batch multiple opts in one commit.

### 5: Benchmark
Same config before/after (`-benchtime`, `-count`, machine load). Report: `ns/op`, `B/op`, `allocs/op`.

### 6: When to Stop
- Remaining CPU in hardware assembly (AES-NI, SIMD) — can't beat hardware
- Remaining allocs from runtime (GC, goroutine stacks, HTTP internals)
- Fix requires custom impl of audited library — security risk > perf gain
- Improvement <5% and within noise

## Pattern Catalog

### Result Caching
**Symptom:** Repeated expensive computation with identical inputs.
**Fix:** Bounded LRU with TTL.
**Safety:** Security-sensitive results: re-validate expiry, bound cache size (DoS), TTL < credential validity.

### Pre-allocation
**Symptom:** High allocs/op from repeated object construction.
**Fix:** Build once at init, share read-only. Safe if immutable after construction.

### Fast-Reject / Short-Circuit
**Symptom:** Expensive validation on clearly invalid inputs.
**Fix:** Cheap structural pre-check (string length before regex, delimiter count before parse).

### Library Swap
**Symptom:** High alloc/CPU in third-party parsing/serialization.
**Fix:** Lower-allocation library (manual scanners, zero-copy, arena).
**Safety:** Security libs: restrict algorithms, verify well-audited, run full test suite.

### Pooling
**Symptom:** High GC from many short-lived same-type objects.
**Fix:** Object pool (sync.Pool, arena). Only for uniform size with clear acquire/release lifecycle.

### Batching
**Symptom:** Many small I/O ops dominating wall-clock.
**Fix:** Batch into fewer calls (batch INSERT, pipeline Redis, buffer writes).

### Artifact Partitioning by Change Frequency
**Symptom:** Small change invalidates large cached artifact.
**Fix:** Separate stable layer (deps) from volatile (app code). Examples: Vite `manualChunks`, Docker deps-first COPY, monorepo per-package builds.

### Dependency Discovery Parallelization
**Symptom:** Sequential resource discovery creates waterfalls.
**Fix:** Declare deps early for parallel fetch. Examples: `<link rel="preconnect">`, `go mod download`, connection pool warm-up, `dns-prefetch`.

### Concurrent-Fetch Dedup
**Symptom:** Duplicate API calls from co-mounted components.
**Fix:** Loading-state guard (semaphore) at store/service layer.
```
async function fetchData() {
    if (isLoading) return
    isLoading = true
    try { data = await api.getData() }
    finally { isLoading = false }
}
```
For advanced: TanStack Query `staleTime`.

## Anti-Patterns
1. Don't optimize runtime internals — fix user code triggering allocations.
2. Don't replace battle-tested crypto with custom.
3. Don't optimize without profiling first.
4. Don't combine multiple opts in one commit.
5. Don't disable security for performance.
6. Don't profile without stable baseline.

## Language Modules

| Module | When |
|---|---|
| [Go](languages/go.md) | Go services, APIs, CLI |
| [Rust](languages/rust.md) | Rust binaries, libraries |
| [Python](languages/python.md) | Python services, CLI, data |
| [Frontend](languages/frontend.md) | Web (JS/TS bundle, rendering, network) |

## Profiling Scripts

| Script | Purpose |
|---|---|
| [go-pprof.sh](scripts/go-pprof.sh) | Go pprof CPU/heap → markdown |
| [frontend-lighthouse.sh](scripts/frontend-lighthouse.sh) | Lighthouse (Core Web Vitals) or bundle analysis |

