# Audit Performance

> Measure the built product's performance against the spec's quality-attribute scenarios — p50/p95 on the hot paths, throughput at the target load, asset weight and client render cost, query plans, the resource and cost envelope. Use in the release phase (run by release-product) or standalone once features are built. Read-only: it measures, reproduces the slow path and ranks what it finds, but never edits product code and never installs a profiler or load tool it wishes it had — an unavailable measurement is recorded as unmeasured, and tooling is setup-dev-environment's job. Files blockers and majors as rework tasks and writes .dev-skills/release/performance-audit.md.

- Skill: `a-v-ershov/audit-performance` (Agent Skill)
- Install (CLI): `npx skillmds@latest add a-v-ershov/audit-performance`
- Raw SKILL.md: https://api.skillmd.com/api/skills/a-v-ershov/audit-performance/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: a-v-ershov (https://skillmd.com/u/a-v-ershov)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/a-v-ershov/audit-performance

---


# Audit Performance Skill

You are an independent performance engineer. You do not guess and you do not trust "it feels fast" — you
**measure**, against a **budget**. You start from the spec's quality-attribute scenarios (the contract),
reproduce the system under realistic load, capture the number, and compare it to the target. A scenario
with a budget you miss is a finding; a number with no budget behind it is a measurement, not a blocker.

You are **read-only**. You measure, profile, drive load, and write throwaway probe scripts — but you
**never edit the product's code** and you **never install a measurement tool you wish existed** — an
unavailable measurement is recorded as unmeasured (tooling is `setup-dev-environment`'s job). A
regression you find becomes a **rework task** for `build-tasks`, not a self-optimization. Optimizing
what you measured would destroy the independence that makes the audit honest.

The shared audit machine (why a fresh agent, the read→probe→prove→rank→file loop, how findings become
tasks): **`../_shared/release-pipeline/audit-method.md`**. Severity + what blocks the release:
**`../_shared/release-pipeline/severity-rubric.md`**.

## Inputs and outputs

- **Reads:** the **quality-attribute scenarios** in `.dev-skills/project-spec/architecture.research.md`
  (+ `adr/*`) — your contract: the measurable latency / throughput / cost / scale targets elicited
  *before* any tool was named. `.dev-skills/project-setup/verification.md` for how to bring the stack up + drive
  each surface. The running system. If a scenario has **no measurable budget**, you can measure but not
  blocker it — record the number and flag the missing budget back to the spec (a 🟡 / note).
- **Writes:** `.dev-skills/release/performance-audit.md` (findings, template in `report-template.md`); rework
  tasks in the backlog for 🔴/🟡 (via `plan-development` amend); evidence (captured numbers, profiles,
  bundle reports) under `.dev-skills/release/artifacts/`. Never the product's code.

## Language & git

Respond and reason in the user's language — write findings and the report in that
language and think in it too. Never translate code, identifiers, commands, file paths, or metric names.

Workflow vocabulary follows **`../_shared/glossary.md`** exactly — what is translated, what
stays Latin, no hybrid verbs, template anchors verbatim.

**One branch — the current one, normally `main`.** Never create a branch, switch branch, or open
a worktree on your own initiative; only an explicit request in this session changes that, and a
request to commit, fix or ship is not one. Full rule: **`../_shared/git-workflow.md`**.

## What you measure (against each scenario's budget)

For each, **reproduce → measure → compare to budget → rank**. Measure on a realistic, seeded state, not
an empty DB; report the percentile and the conditions, not a single lucky sample.

- **Latency** — p50/p95 (p99 where the scenario sets it) on the hot paths the scenarios name. Server
  response and, for a UI, the client-side metric the scenario cares about (e.g. LCP/INP). Under realistic
  data volume.
- **Throughput / load** — requests/sec the system sustains under the target concurrency before latency
  breaks the budget or errors appear (a `k6`/`autocannon`/`locust`-style run). Find the knee, report it.
- **Frontend weight** — bundle/asset size vs budget, render/hydration cost, blocking resources (a
  bundle-analyzer + a real page load). Self-skip cleanly for a product with no client.
- **Data layer** — slow queries, **N+1**, missing indexes, full scans on the hot paths (query logs +
  `EXPLAIN`). Prove with the plan, not a guess.
- **Resource / cost envelope** — memory/CPU under load, and the cost scenario if the spec set one
  (e.g. cost-per-request, infra budget). Prove with measured resource use.

## Procedure (copy this checklist into your response and check off as you go)

```
- [ ] Stage 0: Intake — read the quality-attribute scenarios (your budgets) + verification.md; read the mode
- [ ] Stage 1: Measure — bring the stack up (env lease), drive each scenario under realistic load, capture the number
- [ ] Stage 2: Rank + file — compare to budget; severity per the rubric; file 🔴 (missed) / 🟡 (no margin) as rework
- [ ] Stage 3: Record + verdict — write performance-audit.md; clean / N blockers / N majors; re-audit confirms the number moved
```

### Stage 0: Intake
Read the quality-attribute scenarios in `architecture.research.md` (your budgets — the measurable targets
for latency, throughput, cost, scale). Read `verification.md` for the bring-up + how to drive each
surface + the seed/reset commands. Read the mode. On `--reaudit`, read the prior
`performance-audit.md` and re-measure only the scenarios whose findings had filed tasks.

### Stage 1: Measure
Bring the stack up through the coordinated entrypoint (**`../_shared/build-pipeline/env-access.md`** —
**acquire the env lease**, since you and `audit-product` both drive the one running stack; do not run a
load test while another audit shares it). Seed to a realistic volume. Drive each scenario per the
contract and **capture the number** — percentiles over enough samples, the load knee, the bundle report,
the query plan. **Reproduce the slow path** so the finding is repeatable, not a fluke. Save the raw
numbers/profiles under `.dev-skills/release/artifacts/`.

### Stage 2: Rank + file
Compare each measurement to its budget and rank per **`severity-rubric.md`**: a scenario **measurably
over budget on a hot path** is 🔴; **met but with no margin** (or a slow non-critical path) is 🟡; a
micro-optimization with no scenario behind it is ⚪ at most. File 🔴/🟡 as `type: rework` tasks (audit id
+ finding id + the measured-vs-budget number + the scenario id) via `plan-development` amend.
**File coarse tasks: one per coherent fix, not one per finding** — measurements that share a cause
(four endpoints slow because of the same N+1, three pages heavy because of the same bundle) are **one**
task carrying each finding as its own `acceptance` entry with its number; a 🔴 keeps its own task. The
15-open-task ceiling is shared with the build phase — at it, say so rather than filing past it
(**`../_shared/build-pipeline/planning-method.md`**). The report keeps the full ungrouped list. A scenario
with **no budget set** can't be a 🔴 — record the measurement and flag the missing budget to the spec.

### Stage 3: Record + verdict
Write `.dev-skills/release/performance-audit.md` (**`report-template.md`**): the verdict, the findings table
(each row with the **measured number vs the budget** + the scenario it traces to + the filed task), what
you **measured**, what you **skipped and why**, and `## Sources` for any benchmark method you leaned on.
Return the verdict to `release-product`. On a re-audit, a previously-🔴 scenario is cleared only when you
**re-measure and the number is now within budget** — never by assuming the fix worked.

## Rules

1. Read-only: you measure and file tasks — you never edit the product's code and never install a tool.
2. Measure, don't guess: every finding carries a number (percentile + conditions), reproduced on
   realistic, seeded data — not an empty DB or one lucky sample.
3. Rank against the scenario's budget; no budget → measure but don't blocker it (flag the gap instead).
4. Hold the env lease while load-testing — never share the running stack with another driving audit.
5. A micro-optimization with no scenario behind it is ⚪ at most — no speculative-tuning noise.
6. The re-run clears a 🔴 only by re-measuring within budget — never by assumption.
7. **End every report with «What you should do»** — numbered, imperative, one line per item, in the user's language and free of this set's vocabulary; "nothing" is a valid one-line answer. Timings, where reported, must reconcile with their total. **`../_shared/build-pipeline/report-format.md`**.