Index of every page on this site: llms.txt
All skills
sanoy24 avatar

/backend-performance-review

@ae5828d
Run it yourself

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. 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.

Use this Skill: https://skilld.dev/gh/sanoy24/backend-performance-review/backend-performance-review

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈186 tokens for metadata: the name and description. ≈4.9k when used: this file. ≈222k more on demand in 78 files.

Description uses 9.3% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈744 characters, or 9.3%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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 (Severity/Confidence/Priority, PERF- IDs) is dishonest — those axes measure performance impact, and Informational/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 SEC-, COR-, or MAINT- ID (never PERF-) in the separate "Adjacent findings — outside performance scope" section (templates/review-report.md). Classify it on Kind (security/correctness/maintenance) and Confidence (the same evidence-grade scale — how sure you are it's real, not how much it matters) plus a plain-language Risk note (Low/Medium/High with one sentence of justification) — never Severity or Priority, 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.

Modes

Full review — whole repository. Run all phases.

Change-scoped review — a diff, branch, or PR. Run Phases 0–3 shallowly (enough to place the change in context), then analyze only paths the change touches, plus their immediate callers and the queries they issue. Report only what the change introduces, worsens, or sits directly adjacent to.

Choose change-scoped when the user names a diff, branch, PR, or commit range, or asks "does this change hurt performance". Otherwise full. If ambiguous, ask once.

Change-scoped reviews end in one derived verdict — PASS, WARN, FAIL, or UNKNOWN. UNKNOWN means the change could not be analyzed properly and never collapses into PASS: one says "I looked and found nothing", the other says "I could not look". Load methodology/change-scoped.md for the verdict rules, the expansion boundary, and how to handle a repository's .performance-policy.yml.

Workflow

Phase 0 — Scope and safety

Confirm the mode and that the review is read-only. Set the output budget (§Output budget).

Phase 1 — Discovery

Detect the stack, architecture, and entry points. Run the accelerator if available:

python ${CLAUDE_SKILL_DIR}/scripts/detect_stack.py <repo-path>

It emits JSON with detected languages, frameworks, datastores, caches, brokers, infrastructure, and a references_to_load list. It is an accelerator, never a dependency — if it is missing or errors, inspect manifests manually (see methodology/discovery.md).

Two fields change how you read it. evidence_strength grades each detection — direct (a file that declares the engine), indirect (a declared dependency implying it), weak (an incidental YAML mention), ambiguous (a likely token collision). Anything below direct is a lead to confirm against an actual import or client call, not a fact. And when services holds more than one entry, the repository is not one stack: scope findings to a service, load each service's own references, and disregard the top-level union — it describes no single service accurately.

references_to_load is necessarily partial — it is not the reading list, §Reference routing's table is. The script's list is built entirely from registry.yaml's signal-matched entries; it structurally cannot include a row from §Reference routing's "Always available" table whose trigger is a usage pattern rather than a detected technology — application/data-access.md ("ORM, query construction, N+1"), application/connection-pools.md ("Any pooled client"), and application/serialization.md ("JSON/protobuf, payload size") all apply the moment the code does that thing, independent of which specific library does it. Treat every row of that table as in scope for Phase 4's layer gate, not just the ones the script happened to name.

Inventory observability before anything else. What metrics, traces, logs, benchmarks, load tests, dashboards-as-code, and SLOs exist in the repo? This sets the ceiling on the confidence any finding in this review can reach. Do it now, not at the end. Note any connected telemetry tools (APM, tracing, database monitoring); ask in Phase 2 to read them, read-only, under methodology/runtime-evidence.md.

If the user supplies call-graph, query-shape, or changed-path output, or explicitly opts into an available structural producer, load methodology/structural-evidence.md. Treat its edges as source-located leads to verify, not findings. No structural indexer is required or recommended by default; source inspection remains the fallback.

Load: methodology/discovery.md.

Phase 2 — Workload

Extract repo-derived workload signals and use manifests, configuration, deployment files, observability artifacts, and code to answer question candidates before asking the user. Then apply the decision-change gate in methodology/workload.md: a question survives only when plausible answers can change severity, confidence, or recommendation. Rank survivors by expected decision value and ask zero to seven once, in one message. Seven is a maximum, not a quota.

If the user cannot or will not answer: proceed anyway. Do not block. Record the unknowns and cap workload-dependent findings at Medium confidence.

Load: methodology/workload.md.

Phase 3 — Critical paths

Identify user-blocking request paths, hot background jobs, and shared resources (connection pools, event loops, locks, a single primary database, a shared cache). Work spent off the critical path is worth a fraction of work on it.

Load: methodology/critical-paths.md.

Phase 4 — Layer gates

Determine which layers are actually present. Load only their references, resolved through registry.yaml (see §Reference routing). Do not preload the whole tree.

Phase 5 — Layer analysis

In order, for present layers only: application → data access → database → cache → distributed → infrastructure

Accumulate observations in the private candidate ledger defined by methodology/bottleneck-analysis.md; do not score, recommend, or apply the output budget during discovery.

Phase 6 — Synthesis

Complete the coverage sweep: critical paths, shared resources, write paths, data growth, fixed per-request work, response encoding, and startup and shutdown. Give every candidate a disposition — a real, reachable mechanism is promoted even when minor, bounded, or startup-only; only refuted, unreachable, duplicate, or impact-free candidates are discarded; a deployment-dependent one, whose cost turns on a fact no file states, becomes a workload question — then merge promoted candidates that share a root cause. Score Severity and Confidence and derive Priority from the matrix — never guess it. Apply the output budget only after discovery, disposition, and root-cause merging are complete.

Load: methodology/bottleneck-analysis.md.

Phase 7 — Report

Produce the report using templates/review-report.md. Make its first screen a decision surface in this order: overall assessment, at most three actions, at most three decision-changing unknowns, and at most three validation commands. Those are projections of the complete findings and plans later in the report, never replacements for them. Put detailed evidence, counter-evidence, alternatives, trade-offs, and the complete validation plan after that summary; do not gain brevity by deleting required reasoning.

Every significant recommendation needs a validation path. Include a copyable repository-local command when the evidence supports one, with its purpose and its own production-safety label; omit rather than invent a command. Emit the machine-readable JSON alongside the Markdown (template §10, the bundled schemas/review.schema.json) — the Markdown is authoritative; the JSON is the same content in a form that can be diffed and scored, including any commands under validation.commands. Set "schema_version": "1.0": it is the version of the JSON schema, not of this skill's release, and the validator rejects any other value. Compute each finding's stable_id by running python ${CLAUDE_SKILL_DIR}/scripts/compute_stable_id.py --file <location.file> --symbol <location.symbol> --category <category> — never invent this value by reasoning. Two independently-run reviews were found to disagree completely on a hand-computed stable_id even when they agreed on everything else; the script exists so that stops being possible.

Before finishing, run python ${CLAUDE_SKILL_DIR}/scripts/validate_review.py --review <review.json> and fix every problem it reports until it prints is a valid review. It is the same check publishing applies, bundled with this skill; never substitute a checker of your own, which will miss the rules it does not know.

Load: methodology/validation.md.

Rubrics

Two scored axes. Priority is derived, never chosen.

Confidence — an evidence grade

Level Meaning
Confirmed Runtime evidence that shows the mechanism exists and is cited: profile, EXPLAIN plan, benchmark, trace, metrics export, load-test result. Uncited Confirmed is a violation.
High Follows unambiguously from the code alone. Query in a loop over a variable-length collection; blocking call in an async handler; unbounded query with no LIMIT.
Medium Code pattern plus a stated, unverified workload or data-volume assumption. The assumption goes in Conditions.
Low Plausible only under conditions nothing evidences. Frame as a risk or question, not an assertion.

Workload-dependent findings, where workload is unknown, cap at Medium. Low confidence can never be P0 or P1.

Severity — from four factors

Identify all four for every finding: position (critical path / async / offline), frequency (per request / per item / per batch / rare), growth (O(1), O(log n), O(n), O(n²)+ in data or traffic), blast radius (endpoint / service / system-wide).

Level Criteria
Critical On the critical path and (superlinear growth or saturation of a shared resource). Plausible system-wide failure mode.
High On the critical path, per-request, linear growth in data known or likely to grow; or shared-resource contention from an async path.
Medium Measurable waste on the critical path with bounded growth; or high-frequency work off it.
Low Bounded, local, small constant factor.
Informational No current or projected impact.

Priority — derived

Severity \ Confidence Confirmed High Medium Low
Critical P0 P0 P1 P2
High P0 P1 P1 P2
Medium P1 P2 P2 P3
Low P2 P3 P3 P3
Informational P3 P3 P3 P3

Intervention cost never changes priority. A cheap fix may be tagged quick-win and sequenced early; its priority is unchanged. Priority measures impact, not effort.

Expanded guidance and worked scoring examples: rubrics.md.

Finding format

ID:            PERF-001
Root cause:    ROOT-001                 (findings sharing a cause share this id)
Severity:      Critical | High | Medium | Low | Informational
Confidence:    Confirmed | High | Medium | Low
Priority:      P0 | P1 | P2 | P3      (must match the matrix)
Category:      data-access | concurrency | serialization | io | memory |
               networking | infrastructure | observability | cost
Location:      path/to/file.ext:LINE
Tags:          quick-win | scalability-risk | needs-measurement   (optional)

Problem:              What is wrong, in one or two sentences.
Performance principle: Which universal principle this violates, stated without
                      reference to the technology.
Evidence:             What in the repo supports this — cite files and lines. If there
                      is no runtime evidence, say so here explicitly.
Impact:               Position, frequency, growth, blast radius — made explicit.
Conditions:           The workload under which this matters. If workload is unknown,
                      state the assumption. This field may never be empty.
Counter-evidence:     What you looked for that would refute this, and what you found.
                      "Nothing found" is a valid answer; not looking is not. Anything
                      found here must already be reflected in Confidence.
Why this might not
matter:               The strongest honest case against acting on this. Required at
                      Medium severity and above.
Recommendation:       What to change, and why it addresses the principle rather than
                      the symptom.
Alternatives:         Other options considered, with the preferred one named and why.
                      Required at Medium severity and above.
Trade-offs:           Complexity, memory, consistency, operational burden, new failure
                      modes.
Validation:           How to prove it worked. Specific measurements, each labelled
                      safe-on-production or not-safe-on-production. Include concrete
                      commands with purpose and per-command safety where justified; omit
                      rather than invent them.

Findings sharing a root cause are merged, not enumerated.

Output budget

Full format for the top 10–15 findings by priority. Everything else goes in one ranked table: ID, severity, confidence, priority, location, one-line summary. Deduplicate before capping. The budget controls presentation depth only: it never limits candidate discovery, deletes a surviving finding, or turns a finding into considered_not_reported.

Reference routing

registry.yaml maps detection signals to reference files. Rules:

  • Load the category file before the technology file, always.
  • Load only what the detected stack requires.
  • If a technology has no file, load its category file and note the reduced depth in the report's scope section.

Always available, load as the phase requires. The Category column is which Category: values (§Finding format) that reference file's findings are expected to carry — every value in that enum must appear here at least once; check_repo_invariants.py enforces it, so a new finding category added to SKILL.md without a place to load from fails CI.

When Load Category
Every review methodology/discovery.md, methodology/workload.md, methodology/critical-paths.md, methodology/bottleneck-analysis.md, methodology/validation.md —
Latency or tail-latency questions principles/latency.md —
Capacity, saturation, queueing principles/throughput.md —
Pools, locks, workers, event loops principles/concurrency-and-contention.md concurrency
CPU, memory, I/O, fds, cost, or instrumentation overhead principles/resources.md io, memory, cost, observability
Repeated work, algorithms, N+1 principles/work-and-algorithms.md —
HTTP/gRPC/GraphQL surface application/api.md networking
ORM, query construction, N+1 application/data-access.md data-access
async/await, threads, blocking application/async-and-blocking.md concurrency
JSON/protobuf, payload size application/serialization.md serialization
Any pooled client application/connection-pools.md concurrency
Any datastore databases/universal.md + the category file data-access
Any runtime runtimes/universal.md —
Service-to-service calls distributed/timeouts-and-deadlines.md, distributed/retries-and-backpressure.md networking
A cache exists distributed/caching.md io
A tenant/workspace/account discriminator, shared pool, or shared cache across customers distributed/multi-tenancy.md —
Containers, k8s, autoscaling, serverless infrastructure/resources.md infrastructure

Anti-patterns in your own output

  • A finding with an empty or hand-waved Conditions field.
  • A recommendation with no validation path.
  • "Consider adding caching" with no analysis of hit rate, invalidation, or staleness cost.
  • Reporting a micro-optimization off the critical path above a shared-resource saturation on it.
  • Any number you did not read from a file or receive from the user.
  • A long report that avoids saying "I don't know".

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts1mo3 checks · Risk SAFE
  • Gen Agent Trust Hub1mo

    The skill is a well-structured performance auditing tool with strong safety boundaries, including a read-only mandate and explicit rules against secret exposure. No malicious patterns or security risks were detected.

  • Socket1mo

    No alerts

  • Snyk1mo

    Risk: LOW · No issues

Signed by skilld at ae5828d. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 6 days ago.

Activeupdated last week
metadata
{
  "version": "2.3.0",
  "spec": "backend-performance-review/2.0"
}
All 1 allowed tools
Read Grep Glob Bash(python ${CLAUDE_SKILL_DIR}/scripts/detect_stack.py *) Bash(python3 ${CLAUDE_SKILL_DIR}/scripts/detect_stack.py *) Bash(python ${CLAUDE_SKILL_DIR}/scripts/compute_stable_id.py *) Bash(python3 ${CLAUDE_SKILL_DIR}/scripts/compute_stable_id.py *) Bash(python ${CLAUDE_SKILL_DIR}/scripts/validate_review.py *) Bash(python3 ${CLAUDE_SKILL_DIR}/scripts/validate_review.py *)
Other metadata
compatibility
Requires read access to the target repository. Optional accelerator scripts require Python 3.8+ (standard library only). No network access required.

README badge

README badge for sanoy24/backend-performance-review