plan-forge performance.instructions.md

Performance Patterns (.NET)

Hot Path vs Cold Path

Hot path: Code executed on every request (middleware, auth, routing, serialization). Cold path: Code run infrequently (startup, config reload, migration).

Rules:

• Optimize hot paths aggressively; cold paths can favor readability
• Profile before optimizing — don't guess

Frozen Collections (Hot Config)

// ✅ Use FrozenDictionary for read-heavy lookups (routing, config, tenant mapping)
private static readonly FrozenDictionary<string, TenantConfig> _tenantCache =
    tenants.ToFrozenDictionary(t => t.Id, t => t.Config);

// ✅ Use FrozenSet for membership checks
private static readonly FrozenSet<string> _validRoles =
    new[] { "Admin", "Editor", "Viewer" }.ToFrozenSet();

Source-Generated Logging

// ❌ NEVER on hot paths (allocates params array)
_logger.LogInformation("Processing request for tenant {TenantId}", tenantId);

// ✅ ALWAYS use source-generated (zero-alloc)
[LoggerMessage(Level = LogLevel.Information, Message = "Processing request for tenant {TenantId}")]
partial void LogProcessingRequest(string tenantId);

Source-Generated Regex

// ❌ NEVER compile at runtime
var regex = new Regex(@"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$");

// ✅ ALWAYS use source-generated
[GeneratedRegex(@"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$")]
private static partial Regex EmailRegex();

Async Best Practices

• NEVER use .Result, .Wait(), .GetAwaiter().GetResult() — causes thread pool starvation
• ALWAYS pass CancellationToken through the full call chain
• AVOID Task.Run to wrap synchronous code — keep sync methods sync
• Use ValueTask<T> for methods that often complete synchronously

String Optimization

// ❌ Excessive string allocations
string result = input.ToLower().Replace("-", "").Trim();

// ✅ Use Span<char> for hot paths
ReadOnlySpan<char> span = input.AsSpan().Trim();

Database Performance

• Use CreateReadOnlyConnectionAsync() for SELECT queries (routes to read replicas)
• Batch queries with WHERE id = ANY(@Ids) instead of looping
• Select only needed columns — never SELECT *
• Add indexes for frequently filtered/sorted columns
• Use DataLoaders in GraphQL to prevent N+1