Skip to content
Skills Library
Programming · Analysis

perf-loop

/perf-loop

Profile and optimize a metric under its budget in a disciplined profile-optimize-reprofile loop: benchmark the whole measured set under a fixed environment, find the single highest-leverage hotspot or regression, optimize one thing, re-benchmark the WHOLE set, and repeat until the metric is under target on every measured path with no functional regression. Use for a latency, throughput, page-load, bundle-size, memory, or test-suite-speed target — "optimize until under Nms", "optimize this endpoint until p95 is under 200ms", "make it faster until target", "get page load under budget", "shrink t

Licence
MIT
Last repository change
25.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Profile and optimize a metric under its budget in a disciplined profile-optimize-reprofile loop: benchmark the whole measured set under a fixed environment, find the single highest-leverage hotspot or regression, optimize one thing, re-benchmark the WHOLE set, and repeat until the metric is under target on every measured path with no functional regression. Use for a latency, throughput, page-load, bundle-size, memory, or test-suite-speed target — "optimize until under Nms", "optimize this endpoint until p95 is under 200ms", "make it faster until target", "get page load under budget", "shrink t

Triggers from the description

optimize until under Nmsoptimize this endpoint until p95 is under 200msmake it faster until targetget page load under budget
Original author description

Profile and optimize a metric under its budget in a disciplined profile-optimize-reprofile loop: benchmark the whole measured set under a fixed environment, find the single highest-leverage hotspot or regression, optimize one thing, re-benchmark the WHOLE set, and repeat until the metric is under target on every measured path with no functional regression. Use for a latency, throughput, page-load, bundle-size, memory, or test-suite-speed target — "optimize until under Nms", "optimize this endpoint until p95 is under 200ms", "make it faster until target", "get page load under budget", "shrink t

How it works

  1. The 5-part contract
  2. The proof: a measured number under repeatable conditions, default-FAIL
  3. Step 1 — Read the budget and the benchmark command
  4. Step 2 — Benchmark the whole set, establish/refresh the baseline
  5. Step 3 — Identify the single highest-leverage hotspot
  6. Step 4 — Re-benchmark the WHOLE set, re-run the suite, checkpoint
  7. Guardrails specific to this loop
  8. Choosing the driver primitive
  9. Using it under the orchestrator
  10. How this differs from its neighbors
Original SKILL.md headings · 173 lines, 1,502 words
SKILL.md preview
---
name: perf-loop
version: 1.0.0
description: |
  Profile and optimize a metric under its budget in a disciplined profile-optimize-reprofile loop: benchmark the whole measured set under a fixed environment, find the single highest-leverage hotspot or regression, optimize one thing, re-benchmark the WHOLE set, and repeat until the metric is under target on every measured path with no functional regression. Use for a latency, throughput, page-load, bundle-size, memory, or test-suite-speed target — "optimize until under Nms", "optimize this endpoint until p95 is under 200ms", "make it faster until target", "get page load under budget", "shrink the bundle", "speed up the test suite", "profile and speed this up", "perf loop". The proof is a measured number from a named benchmark artifact.
requires_claude_code: true
min_plan: starter
disable-model-invocation: true
allowed-tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
composes_with: ["loop-controller", "fix-until-green", "performance-agent", "orchestrator"]
spawned_by: ["orchestrator"]
---

# perf-loop

> **A configuration of [`loop-controller`].** That skill supplies the loop
> machinery — primitive selection, the full guardrail stack, state
> externalization. This skill supplies the two things specific to "make it hit
> the budget": a **measured proof under repeatable conditions** (a named
> benchmark artifact, default-FAIL) and the **measurement discipline** that keeps
> a noisy benchmark from lying to the loop. Read `loop-controller` for the
> guardrails; they're inherited, not repeated here.
>
> **Why `disable-model-invocation`:** this loop edits and commits code on its own
> and spends real time re-running benchmarks until a metric is under target. You
> want to *type* `/perf-loop` (or have the orchestrator dispatch it) — not have
> Claude start an autonomous optimize loop because a number looked slow.

## The 5-part contract

| Part | This loop |
|---|---|
| **trigger** | a metric is over its budget (a slow path, a perf regression, a too-big bundle), or an explicit `/perf-loop` (optionally scoped to one path/benchmark) |
| **action** | ONE iteration: **benchmark the whole measured set under fixed conditions** → identify the **single highest-leverage** hotspot/regression → optimize **one thing** → **re-benchmark the WHOLE set** → re-run the functional suite |
| **proof** | the metric is **under target on EVERY measured path** in the benchmark output **AND** the functional suite still exits 0 — default-FAIL: assume over-budget until the benchmark, run under repeatable conditions, proves otherwise |
| **memory** | `perf_baseline.json` (the per-path measured numbers + variance, the durable baseline), `PROGRESS.md` (hotspot → change → delta log), a git checkpoint per measured improvement |
| **stop** | metric under target on every path AND suite green **OR** iteration cap **OR** no-progress for 3 rounds **OR** budget cap |

## The proof: a measured number under repeatable conditions, default-FAIL

"Fast enough" is **not** "the profiler looked better" or "the one path I touched
sped up." It is **every measured path under its target in the benchmark output,
re-measured across the whole set, with the functional suite still green** — and
the benchmark must be reproducible, or the number is noise, not proof. Assume
**over-budget** until you have that artifact. A loop that declares victory off a
single fast run on a warm cache ships a regression the next cold start exposes.

Two rules make the proof trustworthy:

- **A noisy benchmark is a broken proof.** Before any number counts, the
  measurement must be *repeatable*: warm-up runs discarded, a fixed environment
  (same machine/container, no competing load, pinned data set and inputs),
  multiple runs, and reported **variance**. If run-to-run spread is larger than
  the improvement you're claiming, you have measured nothing — tighten the
  harness before optimizing. The repeatable-benchmark checklist and per-stack
  profiling/benchmark tools are in [`references/benchmark-discipline.md`].
- **A speedup that breaks behavior is rejected.** Every optimization re-runs the
  functional suite — **delegate to [`fix-until-green`]**, don't re-implement the
  gate. A change that drops latency but reds a test is not an improvement; it's a
  regression that happens to be fast. The functional gate is part of the proof,
  not a separate concern.

## Step 1 — Read the budget and the benchmark command

Resolve, for *this* project, three things before looping — from
`.claude/profile.yaml` when present (so the same loop works across projects
without hard-coding):

1. **the metric** (p95 latency, page-load ms, bundle KB, peak RSS, suite wall-clock);
2. **the target** (the budget the metric must come in under, per measured path);
3. **the benchmark command** that produces the metric under repeatable conditions.

If the profile doesn't declare them, detect the stack's benchmark/profiling
tooling ([`references/benchmark-discipline.md`] has the per-stack table) and
**confirm the target with the human** — an unstated budget is not a proof. Record
all three in `perf_baseline.json` so every iteration measures the identical thing
the identical way.

## Step 2 — Benchmark the whole set, establish/refresh the baseline

Run the benchmark across **every** measured path under the fixed conditions from
Step 1 (warm-up discarded, multiple runs, variance recorded), and write the
per-path numbers to `perf_baseline.json`. This whole-set baseline is what "no
regression elsewhere" is checked against — a single-path benchmark cannot prove
the loop didn't slow down a neighbor.

## Step 3 — Identify the single highest-leverage hotspot

From the profile, pick the **one** change with the best expected delta-per-effort
— the dominant hotspot or worst regression against baseline, not the first slow
line you see. Optimize **one thing per iteration** (`loop-controller` Step 5):
batching destroys the signal about which change moved the number, and perf changes
routinely interact. Log the chosen hotspot + hypothesis in `PROGRESS.md`.

## Step 4 — Re-benchmark the WHOLE set, re-run the suite, checkpoint

Re-run the **entire** benchmark from scratch — not just the path you touched.
This is `loop-controller`'s "restart the streak": an optimization that speeds one
path while regressing another has made the set worse, and only a whole-set
re-measure catches it. Then re-run the functional suite via [`fix-until-green`]:
no green suite, no accepted improvement.

On a measured improvement (a path closer to budget, nothing regressed, suite
green), **commit a checkpoint** naming the hotspot fixed and the before/after
delta — the git trail is the loop's undo and its post-mortem. When every measured
path is under target and the suite is green, the loop is done; report the final
`perf_baseline.json` and benchmark output as evidence.

## Guardrails specific to this loop

Inherits the full stack from `loop-controller` → `references/safety.md`. The
caps this loop sets:

- **Iteration cap** — default ~10–20 optimize/re-benchmark rounds (read from
  `.claude/profile.yaml` if set). Hitting the cap is a *stop-and-escalate*: some
  budgets aren't reachable without an architectural change, which is a human
  decision, not a license to fake the number.
- **No-progress detection** — if the metric **doesn't improve** across **3
  consecutive iterations** (improvement smaller than the benchmark's own
  variance counts as no improvement), stop and escalate. Three rounds inside the
  noise floor means the approach is wrong or the budget needs revisiting.
- **Budget cap** — re-benchmarking the whole set every round is *slow* (wall-clock
  and, for cloud runners, money). A long perf loop is materially more expensive
  than a quick fix loop; terminate at the ceiling, don't just warn.
- **Never fake the metric.** Forbidden, and each is a *finding* if you catch it:
  weakening the benchmark (fewer iterations, a warmer cache, a smaller data set,
  dropping the slow path from the measured set), loosening the target without
  human sign-off, or reporting a single lucky run instead of the variance-aware
  number. Moving the measuring stick is not a speedup. (`loop-controller`
  guardrail 6, specialized to a measured proof.)
- **Never trade correctness for speed silently.** A faster path that reds a test
  is rejected by the [`fix-until-green`] re-run — that gate is non-negotiable.
- **HITL before irreversible.** Editing source + re-benchmarking is reversible with
  a hard verifier — fine unattended. A change touching an irreversible perf lever
  (a prod-affecting index migration, a cache-infra change) is an HITL checkpoint —
  pause for the human (`loop-controller` guardrail 4).

## Choosing the driver primitive

Per `loop-controller` Step 1, by how you're running it:

- **Default — `/goal`:** the proof is provable from the benchmark output you
  surface each turn, so `/goal "the benchmark reports every measured path under
  its target with run-to-run variance below the margin, and the functional suite
  exits 0 — or stop after N turns."` The evaluator reads the benchmark numbers you
  surface; remember `/goal` has no native budget, so embed the turn cap.
- **Stop-hook gate** when you want the budget check to ship *with* the build and
  block exit deterministically — a perf budget enforced as a wave gate (the
  benchmark script runs, exit non-zero if any path is over target). The
  `stop_hook_active` guard pattern is in `loop-controller`'s `references/safety.md`.

## Using it under the orchestrator

This is the **performance-role inner loop** (archetype 8). The orchestrator
dispatches it to drive a path under budget; it delegates the functional gate to
[`fix-until-green`] and the deep profiling judgment to [`performance-agent`]. The
orchestrator does **not** override a stuck loop — if perf-loop escalates after
no-progress or the cap, that's a real budget blocker (often an architectural one),
not a number to paper over. A satisfied `perf_baseline.json` informs the build;
the `qe-agent`'s `qa-report.json` still decides the gate (`loop-controller`'s
rule: the loop informs, the gate decides).

## How this differs from its neighbors

- **vs. [`fix-until-green`]** — its proof is exit codes (correctness); this loop's
  is a *measured number under repeatable conditions* (speed). perf-loop *composes*
  fix-until-green as its no-regression check — speed on top of, never instead of,
  green.
- **vs. a coverage loop** — both prove a measured artifact, but perf is the only
  loop whose proof is trustworthy *only when the measurement itself is repeatable*
  — variance is a first-class concern, not a footnote.

## Reference files

- [`references/benchmark-discipline.md`] — the repeatable-benchmark checklist
  (warm-up, fixed environment, multiple runs, variance, the noise floor), the
  per-stack profiling/benchmark tooling table (web/page-load, backend latency,
  bundle size, memory, test-suite speed), and the no-functional-regression rule
  (how perf-loop delegates to `fix-until-green`).

[`loop-controller`]: ../loop-controller/SKILL.md
[`fix-until-green`]: ../fix-until-green/SKILL.md
[`performance-agent`]: ../../roles/performance-agent/SKILL.md
[`references/benchmark-discipline.md`]: references/benchmark-discipline.md
Files in this package (2)
  • SKILL.md 11 KB
  • references/benchmark-discipline.md 8 KB

Versions

The database has no other skills named perf-loop.

Database snapshot: 13.11.2026 · package version 49b40f415c98 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100web-perf
    Diagnose and fix web performance through a disciplined measure-first loop. Forces evidence-based optimization: measure → identify bottleneck → fix ONE thing → re-measure → repeat. Prevents guessing. Use when pages load slowly, user mentions performance, LCP, INP, CLS,…
  • 100perf
    The general profile-driven perf loop for any language or runtime: baseline, profile, fix the real hot path, re-measure. Use for /perf, "this is slow", or optimization work.
  • 90perf-profile
    Hotspot detection and performance root-cause analysis: flamegraph interpretation, allocation tracking, latency profiling, regression measurement. Use when a workload misses its latency, throughput, or memory budget; when a benchmark regresses; or before optimizing any hot path…
  • 100autoresearch
    Autonomous experiment loop: edit code, commit, run benchmark, extract metrics, keep improvements or revert, repeat forever. Use this skill when the user asks to "run autoresearch", "start an experiment loop", "optimize a metric autonomously", "autonomous experiments", "benchmark…
  • 100performance-profiling
    Finds and fixes backend and application performance problems by measuring first - define the target metric, reproduce under realistic load, profile CPU, memory, I/O and locks, fix the biggest bottleneck, re-measure, and add a regression guard. Use when code or a service is slow,…
  • 100optimize
    Use when the user wants something measurably improved (speed, latency, memory, binary or index size, build or test time, token or API cost) and wants it done as a disciplined, possibly unattended loop - profile, one change at a time, measure, accept or reject, regression gate,…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.