ForgeLM/.agents/rules/performance-optimization-principles.md

trigger, description

trigger	description
model_decision	When working on performance optimization, profiling, benchmarking, or performance-critical code paths

Performance Optimization Principles

Measure Before Optimizing

"Premature optimization is the root of all evil" - Donald Knuth

Process:

1. Measure: Profile to find actual bottlenecks (don't guess)
2. Identify: Find the 20% of code consuming 80% of resources
3. Optimize: Improve that specific bottleneck
4. Measure again: Verify improvement with benchmarks
5. Repeat: Only if still not meeting performance goals

Don't optimize:

• Code that's "fast enough" for requirements
• Code that's rarely executed
• Without measurable performance problem

Choose Appropriate Data Structures

Selection matters:

• Hash map: O(1) lookup, unordered
• Array/list: O(1) index access, O(n) search, ordered
• Binary tree: O(log n) operations, sorted order
• Set: O(1) membership testing, unique elements

Wrong choice causes performance degradation:

• Using array for lookups: O(n) when O(1) possible with hash map
• Using list for sorted data: O(n log n) sort vs O(log n) tree operations

Avoid Premature Abstraction

Abstraction has costs:

• Runtime overhead (indirection, virtual dispatch, dynamic resolution)
• Cognitive overhead (understanding layers of abstraction)
• Maintenance overhead (changes ripple through abstractions)

Start concrete, abstract when pattern emerges:

• Write straightforward code first
• Identify duplication and common patterns
• Abstract only when there's clear benefit
• Don't add "for future flexibility" without evidence

Optimization Techniques

Caching:

• Store expensive computation results
• Cache database queries, API responses, rendered templates
• Use appropriate cache invalidation strategy
• Set TTL (time-to-live) for cache entries

Lazy Loading:

• Compute only when needed
• Load data on-demand, not upfront
• Defer expensive operations until required

Batching:

• Process multiple items together
• Batch database queries (N queries → 1 query)
• Batch API requests where possible

Async I/O:

• Don't block on I/O operations
• Use async/await for concurrent I/O
• Process multiple I/O operations in parallel

Connection Pooling:

• Reuse expensive resources (database connections, HTTP connections)
• See Resource and Memory Management Principles @resources-and-memory-management-principles.md for pool sizing and configuration

Performance Optimization Checklist

• Is there a measured performance problem (not a guess)?
• Have you profiled to find the actual bottleneck?
• Are appropriate data structures chosen for the access pattern?
• Are expensive operations cached with proper invalidation?
• Are batch operations used instead of N+1 queries?
• Are I/O operations non-blocking where appropriate?
• Have you measured improvement after optimization?

Related Principles

• Resource and Memory Management Principles @resources-and-memory-management-principles.md
• Concurrency and Threading Mandate @concurrency-and-threading-mandate.md
• Concurrency and Threading Principles @concurrency-and-threading-principles.md