/common-performance-engineering

name: common-performance-engineering
description: Enforce universal standards for high-performance development. Use when profiling bottlenecks, reducing latency, fixing memory leaks, improving throughput, or optimizing algorithm complexity in any language.
metadata:
  triggers:
    files:
    - '**/*.ts'
    - '**/*.tsx'
    - '**/*.go'
    - '**/*.dart'
    - '**/*.java'
    - '**/*.kt'
    - '**/*.swift'
    - '**/*.py'
    keywords:
    - performance
    - optimize
    - profiling
    - scalability
    - latency
    - throughput
    - memory leak
    - bottleneck

Performance Engineering Standards

**Priority: P0 (CRITICAL)**

Workflow

1. **Baseline**: Profile before changing anything — measure CPU, memory, and latency. 2. **Identify**: Find top bottleneck (N+1 query, hot loop, memory leak). 3. **Fix**: Apply targeted optimization from sections below. 4. **Verify**: Re-profile to confirm improvement and check for regressions.

Resource Management

• **Memory Efficiency**:
• Avoid memory leaks: explicit cleanup of listeners, observers, and streams.
• Optimize data structures: `Set` for lookups, `List` for iteration.
• Lazy Initialization: Initialize expensive objects only when needed.
• **CPU Optimization**:
• Aim for O(1) or O(n); avoid O(n^2) in critical paths.
• Offload heavy computations to background threads or workers.
• Memoize pure, expensive functions.

See [implementation examples](references/implementation.md) for memoization and batching patterns.

Network & I/O

• **Payload Reduction**: Use efficient serialization (Protobuf, JSON minification) and compression (gzip/br).
• **Batching**: Group multiple small requests into single bulk operations.
• **Caching**: Implement multi-level caching (Memory -> Storage -> Network) with appropriate TTL and invalidation.
• **Non-blocking I/O**: Always use asynchronous operations for file system and network access.

UI/UX Performance

• **Minimize Main Thread Work**: Keep animations and interactions fluid by offloading to workers.
• **Virtualization**: Use lazy loading or virtualization for long lists/large datasets.
• **Tree Shaking**: Ensure build tools remove unused code and dependencies.

Monitoring & Testing

• **Benchmarking**: Write micro-benchmarks for performance-critical functions.
• **SLIs/SLOs**: Define Service Level Indicators (latency, throughput) and Objectives.
• **Load Testing**: Test system behavior under peak and stress conditions; for API workloads, follow [API Performance Testing](../../quality-engineering/quality-engineering-api-performance-testing/SKILL.md) for workload modeling, percentiles, and recovery bounds.

Anti-Patterns

• **No premature optimization**: Profile first, fix proven bottlenecks only.
• **No N+1 queries**: Always batch and paginate data-access operations.
• **No synchronous I/O on main thread**: Async all file/network access.

References

• [Implementation Patterns](references/implementation.md) — profiling patterns, benchmark setup
• [API Performance Testing](../../quality-engineering/quality-engineering-api-performance-testing/SKILL.md) — workload models, latency percentiles, overload recovery