optimization-mastery

<domain_overview>

⚡ OPTIMIZATION MASTERY: THE VELOCITY CORE

Philosophy: Efficiency is the highest form of quality. Minimal overhead, maximum impact. Performance-First is the only law. INTERACTION HYGIENE MANDATE (CRITICAL): Never prioritize synthetic benchmarks over real-world interaction smoothness. AI-generated code often misses Interaction to Next Paint (INP) bottlenecks caused by synchronous main-thread blocking. You MUST use scheduler.yield() or requestAnimationFrame for any complex DOM or state updates triggered by user events. Any implementation that risks "Layout Thrashing" or exceeds the 200ms INP threshold must be rejected. </domain_overview> <frontend_velocity>

🎨 PROTOCOL 1: FRONTEND PRECISION (INP & BUNDLE)

Aesthetics must be fast. Refer to frontend-design for visuals, but enforce these for speed.

1. The INP Threshold:
   • Core Metric: Interaction to Next Paint (INP) MUST be < 200ms.
   • Action: Yield to main thread for heavy logic. Use scheduler.yield() or requestIdleCallback.
2. Hydration Strategies:
   • Mandatory: Use Partial Hydration or Resumability (e.g. Qwik/Astro patterns).
   • Forbidden: Massive "Full Hydration" of static content.
3. Asset Governance:
   • Images: Modern formats (AVIF/WebP) with srcset are mandatory.
   • Fonts: Only wght variable fonts; subsetted. </frontend_velocity> <backend_velocity>

🏗️ PROTOCOL 2: BACKEND VELOCITY (QUERY & DATA)

The backend must be a fortress of speed. Refer to backend-design for architecture.

1. Identifier Strategy:
   • Mandatory: Use UUIDv7 for all primary keys in high-insert tables.
   • Rationale: Time-sortable IDs prevent B-tree fragmentation and boost insert speed by ~30%.
2. Query Budget:
   • Max Latency: Sub-100ms for OLTP queries.
   • Action: Every index MUST be a "Covering Index" for critical read paths.
3. Edge compute:
   • Offload logic to Edge Functions (Vercel/Cloudflare) to reduce Time-to-First-Byte (TTFB). </backend_velocity> <ai_token_stewardship>

🤖 PROTOCOL 3: AI TOKEN STEWARDSHIP (RESOURCE OPS)

AIs are expensive/slow. Optimize the "thought" itself.

1. Context Window Management:
   • Action: Use "Context Folding" (summarizing history) to keep prompts under 4k tokens if possible.
2. Credit-Based Execution:
   • Assign a "Token Budget" to complex tool calling phases.
3. Caching:
   • Implement Semantic Caching for repetitive LLM queries. </ai_token_stewardship> <audit_and_reference>

📂 COGNITIVE AUDIT CYCLE

1. Is INP < 200ms?
2. Are primary keys UUIDv7?
3. Is hydration partial/resumable?
4. Is the token budget justified for this request? </audit_and_reference>