performance-audit

Performance Audit

Purpose

Perform a comprehensive manual performance audit of a codebase. Produce prioritized, evidence-backed findings with file and line references, not generic advice.

Use this skill in review mode unless the user explicitly asks for fixes. The default output is an audit report, not code changes.

Rules

• Audit manually. Do not create or run custom scanner scripts that claim to detect performance issues automatically.
• Use rg, rg --files, git, package metadata, existing tests, existing profiling tools, and normal file reads to gather context.
• Treat search hits as leads only. Read the surrounding code before calling anything a finding.
• Prefer evidence over vibes: call path, data size, frequency, blocking behavior, render scope, query shape, cache behavior, or missing limit.
• Do not benchmark by invention. If you did not measure, say "risk" or "likely", and explain the static evidence.
• Preserve user changes. Do not edit code during an audit unless requested.
• Read references/manual-flags.md for comprehensive flag lists before a broad audit or when assigning subagents.

Workflow

1. Map the system.

   • Inspect repo layout, manifests, build config, runtime entry points, routes, API boundaries, data access layers, database migrations/schema, queues, workers, caches, and observability.
   • Identify likely critical paths: first load, common navigation, hot list/detail views, writes, search/filter, background jobs, realtime sync, dashboard/chart pages, import/export, and high-volume endpoints.
   • Note the stack and skip irrelevant domains, but say what you skipped.

2. Explore in parallel.

   • Use multi_tool_use.parallel for independent shell reads/searches.
   • If multi-agent tools are available, delegate mechanical exploration to fast subagents and deeper pattern review to stronger/smarter subagents.
   • Keep fast subagents focused on candidate discovery: "return files, lines, snippets, and why this is worth manual review; do not make final claims."
   • Keep smart subagents focused on system-level reasoning: "trace the path, identify performance failure modes, cite evidence, and separate confirmed findings from risks."
   • Verify every subagent finding yourself before reporting it.

3. Review manually by domain.

   • For each candidate, trace from user action or job trigger to the expensive work.
   • Ask: how often does this run, how much data can it touch, does it block the user path, does it scale with tenant/user/list size, and does it trigger downstream work?
   • Prefer a few high-confidence findings over a long list of unproven suspicions.

4. Prioritize.

   • P0: Can take down production, cause runaway cost, or block core workflows at realistic scale.
   • P1: User-visible slowness or severe scaling risk on a core path.
   • P2: Meaningful inefficiency, jank, memory growth, or avoidable work on a common path.
   • P3: Local optimization, cleanup, or guardrail that is useful but not urgent.

5. Report findings first.

   • Start with findings ordered by severity.
   • For each finding include: severity, title, file/line, evidence, impact, fix direction, and verification approach.
   • Include open questions or assumptions after findings.
   • Mention audited areas with no major issues only after the findings.
   • If nothing serious is found, say that clearly and list residual risks or unmeasured paths.

Subagent Strategy

Use subagents when the repository is large, polyglot, or likely to contain independent performance surfaces.

Fast exploration subagents are good for:

• Finding entry points, route trees, bundle/build config, dependency-heavy imports, large components, API handlers, ORM usage, migrations, background jobs, cache clients, realtime code, and CSS animation patterns.
• Running targeted rg searches and reading obvious files.
• Producing a candidate map for the main auditor.

Smarter review subagents are good for:

• Tracing first-load and hydration behavior.
• Auditing React/state/render propagation.
• Auditing database access patterns and query scalability.
• Auditing API payload shape, caching, concurrency, and backpressure.
• Auditing realtime/sync architecture.
• Reviewing whether fixes would change behavior or create consistency risks.

Example delegation prompts:

Use $performance-audit at /path/to/performance-audit to inspect this repo's frontend rendering and state-update paths. Return candidate performance risks with file/line evidence. Do not edit files.

Use $performance-audit at /path/to/performance-audit to inspect database and API access patterns. Focus on N+1 queries, unbounded reads, pagination, transactions, cache misuse, and payload size. Return confirmed findings and weaker risks separately. Do not edit files.

Use $performance-audit at /path/to/performance-audit to map build, bundle, asset, and first-load performance risks. Return the files and reasoning a main auditor should verify. Do not edit files.

Useful Manual Search Starters

Use these as leads, not proof:

• Dependency and build surface: package.json, lockfiles, bundler configs, route manifests, server entry points.
• Frontend render surface: useEffect, useMemo, useCallback, memo, observer, Context.Provider, selectors, list rendering, table/grid components.
• Network surface: fetch, axios, graphql, trpc, useQuery, mutate, polling intervals, subscriptions, WebSocket clients.
• Backend surface: route handlers, controllers, resolvers, services, repositories, ORM calls, raw SQL, queue processors.
• Database surface: migrations, indexes, query builders, findMany, joins, include, select, count, offset, transactions.
• Main-thread and memory surface: JSON.parse, JSON.stringify, synchronous storage, sync filesystem calls, timers, event listeners, workers.
• UI jank surface: transition: all, animated width/height/top/left/margin/padding, layout reads after writes, scroll/resize handlers.

Reference

• Read references/manual-flags.md for the comprehensive manual checklist and domain-specific red flags.