performance-optimization

Performance Optimization

Methodology adapted from performance-deity (MIT). Every optimization must be proven with real numbers.

Overview

Optimize code by measuring first, analyzing bottlenecks, applying targeted fixes, and proving improvement with before/after benchmarks. Never guess at performance — measure, fix, verify.

When to Use

• Code review flags slow paths, N+1 queries, or unbounded operations
• /cortexloop performance pass
• User reports latency, jank, or high memory usage
• Before/after a refactor that touches hot paths
• React/Next.js apps with unnecessary re-renders
• API endpoints with missing pagination or eager loading

When NOT to use:

• Code is not on a hot path and no measurable problem exists
• Premature optimization would harm readability without measurable gain
• You cannot run benchmarks in the current environment (note this and use static analysis only)

The Four Phases (Required)

Execute all four phases in order. Do not skip any phase when applying fixes in Direct mode.

Phase 1 — Establish Baseline

1. Identify the exact code path to optimize (function, query, component, endpoint).
2. Run a micro-benchmark:
   • Write a temporary benchmark script in the workspace.
   • Include a warm-up phase (≥10 iterations, discard results).
   • Run ≥100 iterations; record Average and P95 execution time.
   • Run via terminal, then delete the temporary script.
   • Fallback: use time / built-in profilers if the script fails due to missing deps.
3. Record baseline numbers before writing any optimized code.
4. In Report mode, include baseline numbers in the finding even if no fix is applied yet.

Phase 2 — Algorithmic Analysis

State explicitly:

• Time complexity (Big-O) of the current implementation
• Space complexity and primary allocation sites
• Bottleneck in one precise sentence, e.g.:
  • "Nested loops causing O(n²) scaling"
  • "N+1 query: one SELECT per item in loop"
  • "Full table scan — missing index on user_id"
  • "React parent re-render cascades to all list items"
  • "Synchronous file read blocks event loop"