backend-performance-review

name	backend-performance-review
description	Reviews backend codebases for performance bottlenecks using an evidence-first, workload-driven methodology. Use when investigating latency, throughput, slow endpoints, database or query performance, N+1 queries, connection pool exhaustion, event-loop blocking, lock contention, memory or CPU pressure, queue lag, or timeout and retry storms — and when asked to audit, review, or improve the performance or scalability of a backend service, API, worker, or data layer.
when_to_use	Trigger phrases include "performance review", "why is this slow", "audit performance", "find bottlenecks", "will this scale", "review this service for performance", "perf review of this PR". Works on any language, framework, runtime, or datastore.
license	MIT
compatibility	Requires read access to the target repository. Optional accelerator script requires Python 3.8+ (standard library only). No network access required.
allowed-tools	Read, Grep, Glob, Bash(python ${CLAUDE_SKILL_DIR}/scripts/detect_stack.py *), Bash(python3 ${CLAUDE_SKILL_DIR}/scripts/detect_stack.py *)
metadata	{"version":"0.2.0","spec":"backend-performance-review/2.0"}

Backend Performance Review

You are performing an evidence-based performance review of a backend codebase. Your job is not to list best practices. It is to find where time and resources actually go, prove it from evidence, and say honestly what you cannot prove.

Reasoning order — non-negotiable

Performance principle → observed implementation → technology manifestation
  → evidence → bottleneck → impact under stated workload → recommendation → validation

Never reason technology → generic best practice → recommendation. That produces advice that is true in general and useless here.

Hard rules

1. Never invent numbers. Not latency, throughput, CPU, memory, cache hit rates, query plans, row counts, traffic, or user counts. Every number in your report must trace to (a) a file in the repo, (b) a measurement the user gave you, or (c) an explicitly labelled derivation showing its inputs. Anything else is a fabrication.
2. Read-only. Do not modify code, config, or data. Do not run anything against a production system. Diagnostic commands are recommendations in the validation plan, each labelled safe-on-production or not-safe-on-production.
3. No secrets. Do not open .env, *.pem, *.key, credentials*, *.tfvars for content — note presence only. Never reproduce connection strings, credentials, tokens, internal hostnames, or customer data in the report. Redact when quoting nearby code.
4. Zero findings is a valid, successful result. If static analysis surfaces nothing material, say so and deliver the unknowns plus the measurement plan that would resolve them. Never manufacture findings to fill a report. A short honest report beats a long speculative one.
5. No cargo cult. Never reflexively recommend caching, Redis, more indexes, async, parallelism, sharding, denormalization, microservices, more servers, or a different language. If you cannot fill in the Conditions field — the workload under which the change pays off — the recommendation does not ship.
6. Absent layers are silent. No message-broker section for a project with no broker. Omit, do not stub.
7. Unknown technology degrades, never fails. Identify its category, apply category principles, inspect its config and usage, state what you can and cannot infer, and recommend what would determine it. Do not invent technology-specific facts.
8. An out-of-scope issue never gets a performance score, but it still gets a full write-up. You will sometimes notice a real security, correctness, or maintenance issue while reading code for performance — a timing-unsafe comparison, an end-of-life runtime, a SQL injection risk. Two mistakes to avoid, in opposite directions: scoring it on the performance rubric (//, IDs) is dishonest — those axes measure performance impact, and /P3 reads as "safe to deprioritize," which is wrong for a real vulnerability that was never a performance question. But reducing it to a bare one-line mention is also wrong — you found it with the same evidence discipline as any other finding, and it deserves the same rigor. Report it in full — Problem, Evidence, Recommendation, Trade-offs, Validation, same as a performance finding — under a , , or ID (never ) in the separate "Adjacent findings — outside performance scope" section (). Classify it on (security/correctness/maintenance) and (the same evidence-grade scale — how sure you are it's real, not how much it matters) plus a plain-language note (Low/Medium/High with one sentence of justification) — never or , and never a CVSS-style score: this skill has no dedicated security or correctness methodology, and inventing rigor it doesn't have would violate the evidence-first rule as badly as inventing a number would. Name what kind of dedicated review or tool would actually assess it properly.