playbooks

home / skills / xenitv1 / claude-code-maestro / optimization-mastery

optimization-mastery skill

/skills/optimization-mastery

This skill helps you optimize frontend and backend performance by enforcing INP under 200ms, partial hydration, UUIDv7 indexing, and token stewardship.

npx playbooks add skill xenitv1/claude-code-maestro --skill optimization-mastery

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
3.0 KB
---
name: optimization-mastery
description: 2026-grade Cross-Domain Optimization. Expertise in Interaction to Next Paint (INP), Partial Hydration, UUIDv7 indexing, and AI Token Stewardship. Performance is a feature, not an afterthought.
allowed-tools: Read, Write, Edit, Glob, Grep, Bash
---
<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>

Overview

This skill codifies a 2026-grade cross-domain performance playbook that treats performance as a primary feature. It enforces Interaction to Next Paint (INP) limits, Partial Hydration patterns, UUIDv7 indexing, and efficient AI token usage. Use it to audit, implement, and harden frontends, backends, and AI tooling for real-user speed.

How this skill works

The skill inspects runtime interaction paths to detect main-thread blocking and enforces yielding patterns (scheduler.yield(), requestAnimationFrame, requestIdleCallback) to keep INP < 200ms. It evaluates hydration strategy and flags full-hydration anti-patterns, recommending partial hydration or resumability. On the backend, it scans schema and index design, enforcing UUIDv7 for high-insert tables and promoting covering indexes and edge compute where appropriate. For AI integrations it measures prompt token budgets, applies context folding, and recommends semantic caching and credit-based execution.

When to use it

  • During frontend performance audits focused on real-user interaction responsiveness.
  • When designing or migrating hydration strategy for SSR frameworks (avoid full hydration).
  • Before schema design or bulk-write features in high-throughput services.
  • When integrating LLMs to enforce token budgets and reduce cost/latency.
  • When preparing deployments to edge platforms to lower TTFB.

Best practices

  • Prioritize INP over synthetic frame-based metrics; reject any change that risks >200ms INP.
  • Use scheduler.yield(), requestAnimationFrame or requestIdleCallback for heavy event-driven work to avoid layout thrashing.
  • Adopt Partial Hydration or resumability for static pages; hydrate interactive islands only as needed.
  • Use UUIDv7 for primary keys in high-insert tables to keep indexes time-ordered and reduce fragmentation.
  • Create covering indexes for critical read paths and target sub-100ms OLTP queries.
  • Fold conversational context, set explicit token budgets, and implement semantic caching for repeated LLM calls.

Example use cases

  • Audit a single-page app to eliminate INP regressions caused by synchronous state updates.
  • Refactor a server-rendered site from full hydration to partial hydration with interactive islands.
  • Design a high-throughput event ingestion table using UUIDv7 primary keys and covering indexes.
  • Move latency-sensitive endpoints to edge functions to improve TTFB and perceived performance.
  • Optimize an AI assistant pipeline by summarizing history, applying token budgets, and caching responses.

FAQ

What exact INP threshold do you enforce?

INP must be below 200ms for interactive events; anything above is treated as a blocking regression.

Why UUIDv7 instead of UUIDv4 or sequential integers?

UUIDv7 is time-sortable, reducing B-tree fragmentation and improving insert throughput in high-insert workloads while preserving unique distributed IDs.