zuvo:performance-audit

Measure, score, and prioritize performance across the entire stack. Every finding carries an Impact Model (estimated savings, blast radius, confidence level) so the team can act on data instead of hunches.

When to use: Periodic health check, before major release, after heavy feature work, when users report slowness, before scaling infrastructure. When NOT to use: Code quality (zuvo:review), security (/security-audit), test quality (/test-audit).

Guiding Principles

1. Performance claims without measurement are opinions, not findings.
2. "Slow" without a baseline and a target is meaningless.
3. Optimization without profiling is premature optimization.
4. When evidence is absent, report INSUFFICIENT DATA -- never guess.

Mandatory File Loading

Read every file below before starting. Print the checklist.

CORE FILES LOADED:
  1. ../../shared/includes/codesift-setup.md   -- [READ | MISSING -> STOP]
  2. ../../shared/includes/env-compat.md        -- [READ | MISSING -> STOP]
  3. ../../rules/cq-patterns.md                 -- [READ | MISSING -> STOP]
  4. ../../shared/includes/run-logger.md        -- [READ | MISSING -> STOP]
  5. ../../shared/includes/retrospective.md        -- [READ | MISSING -> STOP]
  6. ../../shared/includes/backlog-protocol.md  -- [READ | MISSING -> STOP]   (Filing findings through backlog-add)

If any file is MISSING, STOP. Do not proceed from memory.

Conditional Files

Argument Parsing

Safety Gate

This audit is read-only against production code. The only write targets are zuvo/audits/ and, through backlog-add, memory/backlog.md and memory/findings/. Do not modify source files, configs, build output, or runtime environments. Tooling probes (bundle analysis, Lighthouse) may be invoked but must not alter the build.

MANDATORY TOOL CALLS — Performance Audit Validity Gate

This audit is INVALID if any tool below is skipped when its trigger condition holds. "DEFERRED", "N/A", "--frontend only" are NOT valid reasons for tools relevant to the scoped scope.

Forbidden escape hatches: analyze_complexity: skipped, analyze_hotspots: N/A, codesift: unavailable (when deferred), retrospective: skipped — all REJECTED.

Required POSTAMBLE: report on disk → retro appended → ~/.zuvo/append-runlog exit 0. Every HIGH/MEDIUM finding needs path/to/file.ext:LINE (verify-audit gate).

Mandatory acknowledgment (REQUIRED — print verbatim before Phase 0)

Mandatory-tools-acknowledgment: I will run analyze_complexity + analyze_hotspots + audit_scan + search_patterns(n+1, await-in-loop) + find_clones + trace_call_chain (on cited functions) + analyze_renders/analyze_hooks (when React) + stack-specific tools for this performance audit. Every HIGH/MEDIUM finding will cite a `path/to/file.ext:LINE` resolving in the current tree.

CodeSift preload

Use the deterministic preload helper FIRST. Run ~/.zuvo/compute-preload performance-audit "$PWD" before any ToolSearch. Copy [CodeSift matching trace] verbatim, issue printed ToolSearch(query="select:..."). Math gate enforced.

Phase 0: Detect and Prepare

0.1 Technology Stack Detection

Detect framework, bundler, backend, ORM, and deployment model before analysis. Different stacks exhibit different pathologies.

Frontend signals:

• next.config.* -- Next.js (SSR + RSC + client)
• vite.config.* -- Vite (SPA or SSR)
• webpack.config.* -- Webpack
• svelte.config.* -- SvelteKit
• React / Vue / Angular in dependencies

Dormant-frontend detection: flag as a D2 finding (unused deps) + D9 finding (architectural debt) when any of these are true:

• webpack.config.* returns [] or {} (empty entry)
• package.json declares React/Vue/Webpack but the source tree has zero *.tsx/*.jsx/*.vue files
• assets/ directory is empty and referenced only by dead build scripts

Dormant frontends are a silent cost: install weight, lockfile churn, and CI time for code that never ships. Call them out even when the profile is backend-heavy.

Backend signals:

• @nestjs/core or nest-cli.json -- NestJS
• express in deps -- Express
• fastify in deps -- Fastify
• FastAPI or APIRouter in Python files -- FastAPI
• gin-gonic in Go files -- Gin
• composer.json has yiisoft/yii2 -- Yii2 (PHP)
• composer.json has laravel/framework -- Laravel (PHP)
• composer.json has symfony/framework-bundle -- Symfony (PHP)

ORM / database signals:

• prisma/schema.prisma -- Prisma
• @Entity decorators -- TypeORM
• from sqlalchemy -- SQLAlchemy
• mongoose / mongodb -- MongoDB

Deployment signals:

• vercel.json, netlify.toml -- Serverless edge
• wrangler.toml -- Cloudflare Workers
• Dockerfile -- Containerized
• serverless.yml -- AWS Lambda

Print detection results:

PERFORMANCE STACK
------------------------------------
Frontend:  [React / Next.js / Vue / SvelteKit / none]
Bundler:   [Vite / Webpack / Turbopack / none]
Backend:   [NestJS / Express / FastAPI / Gin / none]
ORM:       [Prisma / TypeORM / SQLAlchemy / none]
Deploy:    [Serverless / Container / Traditional]
------------------------------------

0.2 Profile Selection

Profile E: detect workspace packages, assign profile per package, audit individually, merge into a weighted final report.

Profile F: load rules/yii2.md (if Yii2 detected) for framework-specific performance checks. D11 Runtime pivots from Node.js event-loop checks to opcache/JIT/FPM pool tuning. Apply rules/php.md for general PHP patterns.

0.3 Tooling Probe

Check which measurement tools are available before declaring audit confidence.

Frontend tools:

• Build output with source maps (dist/, .next/, build/)
• Bundle analyzer (source-map-explorer, vite-bundle-visualizer, @next/bundle-analyzer)
• Lighthouse CLI

Backend tools:

• Node.js profiler (clinic, 0x)
• Python profiler (py-spy, cProfile)
• Go profiler (pprof)
• Load tester (autocannon, wrk, k6)

Database tools:

• psql for EXPLAIN ANALYZE (PostgreSQL)
• mongosh for explain plans (MongoDB)

Print the checklist with installed/missing status and install commands for anything missing.

0.4 Audit Confidence Tier

For PARTIAL/MINIMAL audits, include a Prerequisites section in the report listing what is needed to upgrade to FULL.

Phase 1: Hot Path Identification

Performance audits focus on hot paths, not the entire codebase. Identify them before dimension analysis.

1.1 Entry Points

Discover API handlers, page components, middleware, cron jobs, and queue workers. Use CodeSift (search_symbols, trace_route) when available, otherwise grep for framework-specific decorators and route patterns.

1.2 Traffic Estimation

Rank entry points by expected traffic:

1.3 Call Depth Scan

For each high-traffic entry point, trace the call chain (CodeSift trace_call_chain or grep-based import tracing) to find:

• Database queries (N+1, unbounded, missing index)
• External API calls (no timeout, no retry)
• Heavy computation (nested loops, serialization, regex)
• Memory accumulation (unbounded arrays, no streaming)

1.4 Sync I/O Scan

Search for synchronous operations on the event loop:

readFileSync, writeFileSync, execSync, crypto.pbkdf2Sync

These block the thread and are CRITICAL in request handlers, LOW in build scripts or CLI tools.

Phase 2: Dimension Analysis (D1-D12)

Agent Dispatch

Dispatch follows ../../shared/includes/execution-policy.md through env-compat. Reuse existing authorization within that policy; session restrictions take precedence. Run each required gate and report its actual independence or an unmet requirement.

Refer to env-compat.md for the dispatch pattern.

When parallel dispatch is available:

Without parallel dispatch: Execute all dimensions sequentially.

Each agent receives the detected stack, hot path list, and tooling checklist.

D1: Rendering Performance -- Weight 12, Max 12

Score 0-12 based on evidence.

D2: Bundle Size -- Weight 12, Max 12

If bundle analyzer is available, parse the output for precise measurements. Otherwise score from package.json dependency analysis and import patterns.

D3: Asset Optimization -- Weight 8, Max 8

D4: API and Network -- Weight 10, Max 10

D5: Algorithm Complexity -- Weight 10, Max 10

D6: Memory Management -- Weight 10, Max 10

D7: Database Performance -- Weight 12, Max 12, Critical Gate

Critical gate: N+1 in hot path → triggers FAIL. The gate fires on that FINDING; a D7 score of 0 also fires it but is not required.

D8: Caching Strategy -- Weight 8, Max 8

D9: Framework-Specific -- Weight 8, Max 8

Patterns depend on detected stack. Examples:

Next.js: missing loading.tsx, client components fetching data, no generateStaticParams, ISR not configured.

NestJS: missing interceptors for response transform, no request scoping for heavy services, guards running expensive queries.

FastAPI: sync endpoint handlers, missing async def, no connection pooling in Depends.

React: prop drilling causing re-renders, context value unstable reference, uncontrolled form re-renders.

D10: Web Vitals / Core Metrics -- Weight 10, Max 10

If Lighthouse is available, run it and extract scores. Otherwise evaluate from code patterns:

• LCP: largest visible element loading strategy, image optimization, font loading
• INP: event handler complexity, main thread blocking
• CLS: explicit dimensions on images/embeds, font swap strategy

D11: Backend Runtime -- Weight 6, Max 6

D12: Concurrency and Throughput -- Weight 6, Max 6

Phase 3: Verification and Impact Models

3.1 False Positive Filters

3.2 Impact Model Format

Every finding above LOW severity must include an Impact Model:

FINDING: [ID] [SEVERITY] [dimension] -- [description]
  File: [path:line]
  Impact Model:
    Estimated savings: [X ms / X KB / X% CPU -- with reasoning]
    Blast radius:      [N requests/sec affected | N page loads/day]
    Effort:            [S/M/L -- with specific change description]
    Confidence:        [HIGH (measured) | MEDIUM (heuristic) | LOW (estimate)]
    Priority score:    Impact / Effort = [N]

3.3 Severity Classification

Phase 4: Cross-Cutting Analysis

Flag compound patterns that are worse than individual findings:

Phase 5: Report

Save to: zuvo/audits/performance-audit-[YYYY-MM-DD].md — at the project root (zuvo/ resolves via git rev-parse --show-toplevel; override $ZUVO_OUTPUT_DIR. See ../../shared/includes/report-output-location.md).

REQUIRED: emit the Tool Availability Block (template in ../../shared/includes/codesift-setup.md) at the top of the report, after the title and before findings. Auditing degraded runs depends on this — do NOT skip it.

Report Structure

# Performance Audit Report

## Metadata
| Field | Value |
|-------|-------|
| Project | [name] |
| Date | [YYYY-MM-DD] |
| Profile | [A/B/C/D/E] |
| Stack | [detected stack] |
| Audit tier | [FULL / STANDARD / PARTIAL / MINIMAL] |
| Scope | [full / path] |

## Executive Summary

**Score: [N] / [MAX]** -- [grade]

| Metric | Count |
|--------|-------|
| CRITICAL findings | N |
| HIGH findings | N |
| MEDIUM findings | N |
| LOW findings | N |

[2-3 sentence summary with top optimization opportunity and estimated savings]

## Dimension Scores

| # | Dimension | Score | Max | Confidence | Key Finding |
|---|-----------|-------|-----|------------|-------------|
| D1 | Rendering | [N] | 12 | [H/M/L] | |
| D2 | Bundle Size | [N] | 12 | | |
| D3 | Assets | [N] | 8 | | |
| D4 | API/Network | [N] | 10 | | |
| D5 | Algorithms | [N] | 10 | | |
| D6 | Memory | [N] | 10 | | |
| D7 | Database | [N] | 12 | | |
| D8 | Caching | [N] | 8 | | |
| D9 | Framework | [N] | 8 | | |
| D10 | Web Vitals | [N] | 10 | | |
| D11 | Runtime | [N] | 6 | | |
| D12 | Concurrency | [N] | 6 | | |
| **Total** | | **[N]** | **[M]** | | |

N/A dimensions excluded from both score and max.

## Critical Gates
[D7=0 triggers FAIL. List gate status.]

## Findings (sorted by priority score)

[Per finding: ID, severity, dimension, description, Impact Model, fix]

## Cross-Cutting Patterns

[Compound patterns found]

## Optimization Roadmap

### Quick Wins (< 1 hour, high impact)
[Items with highest Priority score = Impact / Effort]

### Short-term (1 day)
[Moderate effort, measurable gains]

### Medium-term (1 week)
[Architectural improvements, caching infrastructure]

### Long-term (1 month+)
[Infrastructure changes, major refactors]

## Prerequisites for Higher Confidence
[If PARTIAL/MINIMAL: what tools to install, what data to collect]

Scoring

Weighted total across active dimensions. N/A dimensions excluded from both numerator and denominator.

Critical gate: an N+1 query in a hot path overrides to FAIL regardless of total. The gate fires on that FINDING, not on D7 scoring 0 — D7 spreads several checks over its weight, so a real N+1 alongside passing checks scores well above zero and would otherwise never block the audit. A D7 score of 0 still fires it; it is simply not necessary.

Backlog Integration

Every HIGH+ finding goes through backlog-add, one call per finding (../../shared/includes/backlog-protocol.md "Filing from a skill"; the bars and the dedupe are the protocol's, so compute no fingerprint and restate nothing). <level> is critical or high.

A Generic write per finding. The class is PERF, and no anchor: ~/.zuvo/backlog-add --repo "$R" --class PERF --conf <N> --source performance-audit --file "$F" --line <n> --evidence "$E" --severity <level> --title "$T". T is stable, D7: <problem> in <symbol> (D7: N+1 in OrderService.list()), and E carries the proposed fix (eager load with include, or batch with where { id: { in: ids } }). A finding that names the input and the wrong result is a BUG instead, filed at the line that shows the defect with an anchor, never at line 1, even when it concerns the whole file: ~/.zuvo/backlog-add --repo "$R" --class BUG --conf <N> --source performance-audit --file "$F" --line <n> --anchor "$A" --evidence "$E" --severity <level> --title "$T", with A copied from that line and E the input, the wrong result, and the proposed fix. A PERF finding that holds for the whole file is a whole-file finding (--line 1, a "Whole file: ..." title).

A finding measured on a URL or by a tool (Lighthouse, bundle analysis) with no repository line causing it is a target record, with no anchor: ~/.zuvo/backlog-add --repo "$R" --class PERF --conf <N> --source performance-audit --target "$U" --evidence "$E" --severity <level> --title "$T", U the page URL (no query string) and E the measurement and the proposed fix. A secret or user data is never copied into a record (backlog-protocol.md "Filing from a skill", "The location rule", the secrets sentence).

Assign "$R", "$T" and "$E" before each call, "$F" only for a file finding, "$A" only for a BUG, "$U" only for a target finding, as "Free text goes through a variable" in that section says; an empty value you pass is a bug, and backlog-add refuses a missing required field (REFUSED missing-field:<f>). Report the B- or F-id each call prints and Recorded: N (backlog: a, ledger: b) ("The report line" in backlog-protocol.md), plus each NOT PERSISTED (<reason>) by name; on a non-zero exit act on the protocol's exit table, and never append by hand.

This audit does not commit: it stages nothing. It lists the wrote= paths backlog-add printed as Backlog writes: <path>, ... (Backlog writes: none when there are none), in its report for the user when it runs standalone, and in its report for the calling skill's closing commit to carry when another skill runs it (backlog-protocol.md "Filing from a skill", Committing what backlog-add wrote).

Phase 6: Next-Step Routing

RECOMMENDED NEXT ACTION
------------------------------------
D7 CRITICAL (N+1)        -> zuvo:refactor [service file]
D2 > 500 KB bundle       -> tree-shake + code-split (direct fix)
D11 sync I/O on event loop -> zuvo:refactor [handler file]
D4 no timeouts           -> direct fix (add AbortSignal)
Score < 60%              -> prioritize quick wins, re-audit in 2 weeks
Score >= 85%             -> schedule next audit in 3 months
------------------------------------

Completion Gate Check

Before printing the final output block, verify every item. Unfinished items = pipeline incomplete.

COMPLETION GATE CHECK
[ ] Profile selected and printed (A/B/C/D/E) with active dimensions
[ ] Audit confidence tier declared (FULL/STANDARD/PARTIAL/MINIMAL)
[ ] Hot path identification ran
[ ] Every HIGH+ finding has Impact Model with estimated savings
[ ] D7 critical gate printed (N+1 in hot path)
[ ] Report saved to zuvo/audits/ with optimization roadmap
[ ] Run: line printed and appended to log

PERFORMANCE-AUDIT COMPLETE

Score: [N] / [MAX] -- [grade] Profile: [A/B/C/D/E] | Audit tier: [FULL/STANDARD/PARTIAL/MINIMAL] Dimensions: [N scored] | Critical gates: [PASS/FAIL] Findings: [N critical] / [N total]

Validity Gate (REQUIRED — print BEFORE Run line, AFTER retro append + append-runlog)

VALIDITY GATE
  triggers_held: language=<X> framework=<X> react=<yes|no> orm=<prisma|drizzle|none>
  required_tool_calls:
    analyze_complexity: [<max_cc> max | NOT_CALLED — VIOLATES_TRIGGER]
    analyze_hotspots: [<top_N> hotspots | NOT_CALLED — VIOLATES_TRIGGER]
    audit_scan: [<N> findings | NOT_CALLED — VIOLATES_TRIGGER]
    search_patterns: [<N> hits | NOT_CALLED — VIOLATES_TRIGGER]
    find_clones: [<N> clusters | NOT_CALLED — VIOLATES_TRIGGER]
    trace_call_chain: [<N> chains | not_required | NOT_CALLED — VIOLATES_TRIGGER]
    analyze_renders/analyze_hooks: [<N> | not_required (no React) | NOT_CALLED — VIOLATES_TRIGGER]
    stack_specific: [<result> | not_required | NOT_CALLED — VIOLATES_TRIGGER]
  postamble:
    retros_log_appended: [yes(bytes_added=N) | NOT_APPENDED]
    retros_md_appended: [yes(entry_count=N) | NOT_APPENDED]
    verify_audit_pass: [yes(<verified>/<total>) | NOT_RUN | REJECTED]
  gate_status: [PASS | FAIL — <which gates missing>]

If gate_status = FAIL → VERDICT = INCOMPLETE.

Append the Run line via the retro-gated wrapper (NOT direct >> runs.log):

printf '%b\n' "$RUN_LINE" | ~/.zuvo/append-runlog

Run: <ISO-8601-Z> performance-audit <project> <N-critical> <N-total> <VERDICT> - <N>-dimensions <NOTES> <BRANCH> <SHA7> <INCLUDES> <TIER>

Retrospective (REQUIRED)

Follow the retrospective protocol from retrospective.md. Gate check → structured questions → TSV emit → markdown append. If gate check skips: print "RETRO: skipped (trivial session)" and proceed.

After printing this block, append the Run: line value (without the Run: prefix) to the log file path resolved per run-logger.md.

VERDICT: PASS (0 critical findings), WARN (1-3 critical), FAIL (4+ critical).

Execution Notes

• All commands use the resolved TARGET_ROOT from argument parsing
• CodeSift integration follows codesift-setup.md -- use indexed search when available, fall back to Grep/Read/Glob when not
• Agent dispatch follows env-compat.md -- parallel when supported, sequential otherwise
• Impact Models are the primary decision tool -- findings without an Impact Model are informational only
• Confidence levels are strict: only profiler/Lighthouse/EXPLAIN output earns HIGH confidence; code inspection maxes out at MEDIUM