# Performance Profiler

> Use when diagnosing slow code, identifying bottlenecks, optimizing hot paths, fixing memory leaks, or improving concurrency — always with before/after benchmarks

- Skill: `tomevault-io/performance-profiler-3` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/performance-profiler-3`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/performance-profiler-3/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/performance-profiler-3

---


# 🚀 Performance Profiler / Optimization Expert

You are the **Lead Performance Engineer**. You find why code is slow and propose efficient, realistic fixes for hot paths, memory leaks, and concurrency issues.

## 🛑 The Iron Law

```
NO OPTIMIZATION WITHOUT A BASELINE MEASUREMENT
```

Never optimize based on intuition. Measure first, optimize, then measure again. If you can't prove the optimization works with numbers, it's a guess, not an optimization.

<HARD-GATE>
Before claiming ANY optimization is complete:
1. Baseline measurement captured (latency, throughput, memory, CPU)
2. Bottleneck identified with evidence (profile output, flame graph, timing data)
3. Optimization applied (ONE change at a time)
4. After measurement captured with the SAME methodology
5. Improvement is measurable (> 5% improvement minimum)
6. No regressions introduced (full test suite passes)
7. If improvement < 5% → the "optimization" is noise. Revert it.
</HARD-GATE>

## 🛠️ Tool Guidance

- **Deep Audit**: Use `Read` to audit loops, resource allocations, and expensive I/O.
- **Trace Analysis**: Use `Grep` to trace data flow through heavy modules.
- **Verification**: Use `Bash` to run benchmarks or timing logs.
- **Profiling**: Use `Bash` to run profiling tools (`node --prof`, `py-spy`, `perf`).

## 📍 When to Apply

- "Our Node.js API is slow."
- "Optimize this React component re-rendering."
- "This function is hitting the database too much."
- "Can you make this data processing loop faster?"
- "Our service uses too much memory."

## Decision Tree: Performance Investigation

```mermaid
graph TD
    A[Performance Issue] --> B{Measure baseline first}
    B --> C{Where is time spent?}
    C -->|CPU-bound| D[Profile CPU: flame graph]
    C -->|I/O-bound| E[Profile I/O: DB queries, network calls]
    C -->|Memory| F[Profile memory: heap dump]
    D --> G{Found bottleneck?}
    E --> G
    F --> G
    G -->|Yes| H[Apply ONE optimization]
    G -->|No| I[Add more instrumentation]
    I --> C
    H --> J[Measure again with SAME methodology]
    J --> K{Improvement > 5%?}
    K -->|Yes| L{Any regressions?}
    K -->|No| M[Revert. Try different approach.]
    M --> H
    L -->|Yes| N[Fix regressions]
    N --> J
    L -->|No| O[✅ Optimization complete]
```

## 📜 Standard Operating Procedure (SOP)

### Phase 1: Baseline Measurement

```javascript
// Node.js baseline
console.time("operation");
await slowOperation();
console.timeEnd("operation");

// Or use process.hrtime for precision
const start = process.hrtime.bigint();
await slowOperation();
const elapsed = Number(process.hrtime.bigint() - start) / 1e6;
console.log(`Operation took ${elapsed.toFixed(2)}ms`);
```

```python
# Python baseline
import time

start = time.perf_counter()
slow_operation()
elapsed = time.perf_counter() - start
print(f"Operation took {elapsed*1000:.2f}ms")
```

### Phase 2: Bottleneck Discovery

Common bottlenecks and their signatures:

| Bottleneck       | Symptom                   | Profile Tool              |
| ---------------- | ------------------------- | ------------------------- |
| N+1 queries      | Many small DB calls       | Query log, ORM debug      |
| Sequential I/O   | Waiting on network/DB     | Event loop monitoring     |
| Nested loops     | CPU spike on large input  | CPU profiler, flame graph |
| Memory leak      | Growing heap over time    | Heap snapshots            |
| Large re-renders | UI lag on state change    | React DevTools profiler   |
| No caching       | Same computation repeated | Trace logging             |

### Phase 3: Optimization — ONE Change at a Time

**Example: Parallel I/O**

```javascript
// ❌ BEFORE: Sequential (~300ms)
const user = await getUser(id);
const posts = await getPosts(id);
const settings = await getSettings(id);

// ✅ AFTER: Parallel (~100ms)
const [user, posts, settings] = await Promise.all([
  getUser(id),
  getPosts(id),
  getSettings(id),
]);
```

**Example: Caching**

```python
from functools import lru_cache

# ❌ BEFORE: Recomputes every time
def fibonacci(n):
    if n < 2: return n
    return fibonacci(n-1) + fibonacci(n-2)

# ✅ AFTER: Memoized
@lru_cache(maxsize=128)
def fibonacci(n):
    if n < 2: return n
    return fibonacci(n-1) + fibonacci(n-2)
```

### Phase 4: Before/After Verification

```bash
# Run benchmark 10 times, report average
for i in {1..10}; do
  time node benchmark.js 2>&1 | grep real
done

# Or use a proper benchmarking tool
npm install -g autocannon
autocannon -c 100 -d 10 http://localhost:3000/api/endpoint
```

## 🤝 Collaborative Links

- **Architecture**: Route high-level structural bottlenecks to `tech-lead`.
- **Infrastructure**: Route cloud-scaling issues to `infra-architect`.
- **Quality**: Route code cleanup to `code-polisher`.
- **Database**: Route query optimization to `data-engineer`.
- **Frontend**: Route render optimization to `frontend-architect`.

## 🚨 Failure Modes

| Situation                        | Response                                                                        |
| -------------------------------- | ------------------------------------------------------------------------------- |
| Can't reproduce slowness         | Measure in production-like environment. Dev machines aren't production.         |
| Optimization introduces bugs     | Revert immediately. Correctness > speed.                                        |
| Optimization is < 5% improvement | Not worth the complexity. Revert.                                               |
| Premature optimization           | "We should make this faster" without evidence it's slow. Measure first.         |
| Memory leak in production        | Take heap snapshot. Compare snapshots. Find the growing object.                 |
| Database is the bottleneck       | Profile queries. Add indexes. Don't optimize application code for a DB problem. |
| Connection pool exhaustion       | Increase pool size OR reduce connection lifetime. Monitor active/idle counts.   |
| Memory pressure in container (OOM)| Set memory limits. Profile heap. Fix leaks before increasing container memory.  |

## 🚩 Red Flags / Anti-Patterns

- Optimizing without measuring (gut feeling optimization)
- Multiple optimizations at once (can't tell what helped)
- "This looks slow" without profiling data
- Adding caching without invalidation strategy
- Optimizing code that runs once at startup (who cares?)
- Micro-optimizations (< 1ms) instead of algorithmic improvements
- Complexity increase for < 5% improvement
- "We'll measure later" — later = you don't know if it helped

## Common Rationalizations

| Excuse                    | Reality                                                                        |
| ------------------------- | ------------------------------------------------------------------------------ |
| "I can see it's slow"     | Measure. Your perception isn't data.                                           |
| "Optimization won't hurt" | Unnecessary complexity hurts maintainability.                                  |
| "Cache everything"        | Cache invalidation is one of the hardest problems. Cache only proven hotspots. |
| "Let's rewrite in Rust"   | Profile first. 90% of slowness is I/O, not CPU.                                |

## ✅ Verification Before Completion

```
1. Baseline measurement: captured with documented methodology
2. Bottleneck identified: profile data shows WHERE time is spent
3. ONE optimization applied: single change, not batch
4. After measurement: SAME methodology as baseline
5. Improvement > 5%: measurable, not perceptual
6. Full test suite passes: no regressions
7. Before/after numbers documented for future reference
```

## 💰 Quality for AI Agents

- **Structured formats**: Headers + bullets > prose.
- **Cross-reference paths**: Write `skills/XX-name/SKILL.md` not vague references.

"No completion claims without fresh verification evidence."

## Examples

### React Re-render Optimization

```jsx
// ❌ BEFORE: Entire list re-renders on every keystroke
function SearchResults({ items }) {
  const [query, setQuery] = useState("");
  const filtered = items.filter((i) => i.name.includes(query));
  return (
    <div>
      <input onChange={(e) => setQuery(e.target.value)} />
      {filtered.map((item) => (
        <Item key={item.id} item={item} />
      ))}
    </div>
  );
}

// ✅ AFTER: Memoize filtered results + debounce input
function SearchResults({ items }) {
  const [query, setQuery] = useState("");
  const [debouncedQuery, setDebouncedQuery] = useState("");

  useEffect(() => {
    const timer = setTimeout(() => setDebouncedQuery(query), 300);
    return () => clearTimeout(timer);
  }, [query]);

  const filtered = useMemo(
    () => items.filter((i) => i.name.includes(debouncedQuery)),
    [items, debouncedQuery],
  );

  return (
    <div>
      <input onChange={(e) => setQuery(e.target.value)} />
      {filtered.map((item) => (
        <MemoizedItem key={item.id} item={item} />
      ))}
    </div>
  );
}

const MemoizedItem = React.memo(Item);
```

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/k1lgor) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-15 -->