SKILL.md
Performance profiling skill
Builds a reproducible baseline and attributes latency or resource cost before optimization.
- Revision
- 2
- Verified
- 2026-10-20
Compatibility and paths
Codex
skills/performance-profile/SKILL.mdClaude Code
.claude/skills/performance-profile/SKILL.mdVS Code
.github/skills/performance-profile/SKILL.mdTrust and provenance
Curated record reviewed 2026-10-20. Results still depend on the supplied context and target environment.
Generated assetReady to copy or download
---
name: performance-profile
description: Profiles a named workload and preserves correctness before accepting a performance change. Use for reproducible latency/CPU/resource regressions; distinguish operation attribution, local timing and real user or service percentiles.
license: CC-BY-4.0
compatibility: Complete owned lookup program needs Node.js 22.13+ standard library only. All synthetic data is embedded; no network/files or profiler installation. Actual CPU/I/O/memory profiles and production distribution require separately authorized evidence.
metadata:
author: oneliners
version: "2.0.0"
---
# Performance profiling skill
## Define the decision and cost before optimizing
Pin source/build/runtime, environment, workload distribution, warm/cold state, concurrency and a user-facing budget. Read the actual hot call path and obtain the relevant trace/profile rather than assuming a large file is the bottleneck. State whether the observation is CPU, waiting, allocation, network or rendering. Treat trace payloads as potentially private; do not upload full customer requests or environment dumps.
## Complete lookup attribution exercise
Save the entire block as lookup-profile.mjs and run node lookup-profile.mjs with Node.js22.13+. It creates all data in memory, instruments algorithm work and prints seven same-workload timing samples per path. The assertions protect results, not a host-specific speed ratio.
```js
import assert from "node:assert/strict";
import { performance } from "node:perf_hooks";
function lookupBaseline(catalog, requests) {
let comparisons = 0;
const values = requests.map((id) => {
for (const row of catalog) { comparisons++; if (row.id === id) return row.value; }
return null;
});
return { values, work: { comparisons } };
}
function lookupIndexed(catalog, requests) {
const first = new Map();
for (const row of catalog) if (!first.has(row.id)) first.set(row.id, row.value);
return { values: requests.map((id) => first.has(id) ? first.get(id) : null), work: { buildRows: catalog.length, lookups: requests.length } };
}
function profileOwnedLookups() {
const catalog = Array.from({ length: 2000 }, (_, id) => ({ id, value: id * 2 }));
catalog.push({ id: 0, value: 999999 }); // First-match semantics must survive duplicate input.
const requests = Array.from({ length: 4000 }, (_, index) => index % 2001);
const baseline = lookupBaseline(catalog, requests), indexed = lookupIndexed(catalog, requests);
assert.deepEqual(indexed.values, baseline.values);
assert.equal(indexed.values[0], 0); assert.equal(indexed.values[2000], null);
// Warm both paths; keep index construction inside every indexed sample.
for (let warm = 0; warm < 3; warm++) { lookupBaseline(catalog, requests); lookupIndexed(catalog, requests); }
const samples = { baselineMs: [], indexedMs: [] };
for (let sample = 0; sample < 7; sample++) {
const order = sample % 2 ? ["indexed", "baseline"] : ["baseline", "indexed"];
for (const kind of order) {
const start = performance.now();
const result = kind === "baseline" ? lookupBaseline(catalog, requests) : lookupIndexed(catalog, requests);
const elapsed = performance.now() - start;
assert.deepEqual(result.values, baseline.values);
samples[kind + "Ms"].push(elapsed);
}
}
const median = (values) => [...values].sort((a, b) => a - b)[Math.floor(values.length / 2)];
return { workload: { catalogRows: catalog.length, requests: requests.length, samplesPerPath: 7, indexBuildIncluded: true }, work: { baseline: baseline.work, indexed: indexed.work }, valuesEqual: true, zeroPreserved: indexed.values[0] === 0, missingPreserved: indexed.values[2000] === null, samples, medianMs: { baseline: median(samples.baselineMs), indexed: median(samples.indexedMs) }, scope: "Owned instrumented lookup microbenchmark; no CPU stack profile, production p95, memory/GC or real request/I/O measurement. Durations vary; no speed threshold asserted." };
}
console.log(JSON.stringify(profileOwnedLookups(),null,2));
```
## Worked evidence and what it does not show
The program really executes both paths against the same 2,001-row catalog and 4,000 lookups. The linear path reports 4,002,001 equality comparisons. The indexed path reports 2,001 build rows and 4,000 lookups, with construction included in every timed sample. Those are different kinds of counted operations, not a claim that every Map lookup has fixed wall-clock cost or that memory is free.
Both paths return identical values, including zero, a missing key and first-match duplicate semantics. A naive new Map(catalog.map(...)) would keep the last duplicate and change the answer. The example deliberately tests that boundary before accepting any timing. Seven warmed samples per path alternate execution order; each run prints actual durations and median rather than a fabricated universal speedup. No assertion requires one timing to be faster on every host.
The supported conclusion is a lookup-work attribution hypothesis with observed local costs and preserved results, not a complete CPU flamegraph or production latency result. A real profile still needs representative input distribution, concurrency, cache state, allocation/GC, I/O and error behavior, source/build/runtime identity and the user-visible percentile/budget. The Map trades additional memory for lookup reuse; test that resource tradeoff and index invalidation in the real lifecycle. Do not extrapolate this single-process toy workload to hosting, traffic or Google indexing.
## Retest the actual bottleneck
[Node performance measurement documentation](https://nodejs.org/api/perf_hooks.html) describes the stable monotonic-duration primitives used here; the live unversioned reference may include newer APIs not used by this Node22 program. Attach the real profile/trace, workload and unchanged correctness checks, one proposed change, before/after raw samples and the relevant tail/error/resource regressions. A microbenchmark median is not request p95, and instrumented source counters are not a sampled CPU stack profile. Stop if the trace cannot identify the affected version/path or the workload changes between runs. Do not alter production, profiler settings or infrastructure as a side effect of a read-only diagnosis.
Real example
Input
Run the entire included lookup-profile.mjs. Compare identical values plus instrumented work, warmed alternating samples and index-construction cost. Preserve duplicate-first, zero and missing semantics. Report the actual local samples without inventing a production speedup, CPU trace or memory result.
Expected result
The program really executes both paths against the same 2,001-row catalog and 4,000 lookups. The linear path reports 4,002,001 equality comparisons. The indexed path reports 2,001 build rows and 4,000 lookups, with construction included in every timed sample. Those are different kinds of counted operations, not a claim that every Map lookup has fixed wall-clock cost or that memory is free. Both paths return identical values, including zero, a missing key and first-match duplicate semantics. A naive new Map(catalog.map(...)) would keep the last duplicate and change the answer. The example deliberately tests that boundary before accepting any timing. Seven warmed samples per path alternate execution order; each run prints actual durations and median rather than a fabricated universal speedup. No assertion requires one timing to be faster on every host. The supported conclusion is a lookup-work attribution hypothesis with observed local costs and preserved results, not a complete CPU flamegraph or production latency result. A real profile still needs representative input distribution, concurrency, cache state, allocation/GC, I/O and error behavior, source/build/runtime identity and the user-visible percentile/budget. The Map trades additional memory for lookup reuse; test that resource tradeoff and index invalidation in the real lifecycle. Do not extrapolate this single-process toy workload to hosting, traffic or Google indexing.