caching-strategy

name: "caching-strategy" department: "tuner" description: "Use when designing or auditing a caching architecture. Covers multi-layer cache hierarchy, key schema, TTL policies, invalidation flows, and warming strategies. Do not use for runtime performance profiling (use performance-audit) or capacity planning (use load-modeling)." version: 1 triggers: - "cache" - "caching" - "CDN" - "stale" - "invalidation" - "TTL" - "edge" - "stale-while-revalidate"

Caching Strategy

Purpose

Design a multi-layer caching architecture that minimizes latency and server load while maintaining data freshness. Produces a cache hierarchy diagram, key schema, TTL policy table, and invalidation flow for each cacheable resource.

Scope Constraints

Reads: Application architecture diagrams, resource inventories, access pattern logs, existing cache configuration, Cache-Control headers, CDN settings.
Cannot: Profile runtime performance bottlenecks or measure Core Web Vitals (use performance-audit). Cannot model traffic growth or define scaling triggers (use load-modeling). Cannot provision CDN or cache infrastructure.

Inputs

Application architecture (server framework, database, CDN provider)
Resource inventory (pages, API responses, static assets, database queries)
Access patterns (read/write ratio, update frequency, personalization requirements)
Freshness requirements (how stale can each resource be before it hurts the user?)
Current caching setup (if any) and known pain points

Input Sanitization

No user-provided values are used in commands or file paths. All inputs are treated as read-only analysis targets.

Procedure

Progress Checklist

Step 1: Identify cacheable resources and access patterns
Step 2: Design cache hierarchy
Step 3: Define cache key schema
Step 4: Specify TTL policies per resource type
Step 5: Design invalidation strategy
Step 6: Plan stale-while-revalidate patterns
Step 7: Specify cache warming strategy for cold starts

Step 1: Identify Cacheable Resources and Access Patterns

Inventory all resources served by the application:

Static assets (JS, CSS, images, fonts) — versioned or content-hashed?
HTML pages — fully static, SSG, SSR, or dynamic?
API responses — public or user-specific? How often do underlying data change?
Database query results — read frequency vs write frequency per table/query
Computed/aggregated data — dashboards, reports, search indexes

For each resource, document the read:write ratio and acceptable staleness window.

Step 2: Design Cache Hierarchy

Define what is cached at each layer, from closest to the user outward:

Browser cache — immutable versioned assets, prefetched resources
CDN / Edge cache — public HTML, public API responses, optimized images
Application cache — session data, computed results, frequently-accessed records
Database query cache — prepared statement results, materialized views

Document which layer is the primary cache for each resource type.

Step 3: Define Cache Key Schema

Design consistent, collision-free cache keys:

Include resource type, identifier, and variant (e.g., page:blog:slug:v2:locale:en)
Account for personalization dimensions (user role, locale, feature flags)
Define key namespacing to support bulk invalidation (e.g., page:blog:*)
Document key generation patterns for each resource type

Step 4: Specify TTL Policies per Resource Type

Assign time-to-live values based on staleness tolerance:

Immutable assets — long TTL (1 year) with content-hash cache busting
Semi-static content (blog posts, product pages) — medium TTL (minutes to hours)
Dynamic/personalized content — short TTL (seconds) or no-cache with revalidation
API responses — TTL matched to underlying data change frequency

Document TTL as both max-age and s-maxage where CDN behavior differs from browser.

Step 5: Design Invalidation Strategy

Define how stale cache entries are removed or refreshed:

Event-driven invalidation — cache purge triggered by data mutations (webhook, pub/sub)
Time-based expiry — TTL-only, no active invalidation
Versioned keys — new key on data change, old key expires naturally
Tag-based invalidation — associate cache entries with tags, purge by tag

Map each resource to its invalidation method. Document the mutation-to-purge flow.

Step 6: Plan Stale-While-Revalidate Patterns

Design graceful degradation for cache misses:

Which resources support stale-while-revalidate? Define the stale window.
Which resources require strict freshness (financial data, auth state)?
Define fallback behavior when the origin is unavailable (serve stale? show error?)
Document Cache-Control header construction for each resource class

Step 7: Specify Cache Warming Strategy for Cold Starts

Plan for empty caches after deployments, CDN purges, or scaling events:

Which resources should be pre-warmed? (High-traffic pages, critical API responses)
Warming method — build-time generation, deployment hook, background job, on-demand
Warming priority order — warm the hottest paths first
Cold start latency budget — acceptable response time before cache is warm

Compaction resilience: If context was lost during a long session, re-read the Inputs section to reconstruct what system is being analyzed, check the Progress Checklist for completed steps, then resume from the earliest incomplete step.

Handoff

If profiling reveals bottlenecks beyond caching (render path, bundle size, database queries), hand off to tuner/performance-audit for full-stack performance analysis.
If cache warming or invalidation volume suggests infrastructure scaling concerns, hand off to tuner/load-modeling for capacity planning and cost projections.

Output Format

# Caching Strategy: [Application Name]

## Cache Hierarchy

[User] → Browser Cache → CDN/Edge → App Cache → DB Query Cache → [Database]


| Layer | Resources Cached | TTL Range | Invalidation |
|-------|-----------------|-----------|-------------|
| Browser | ... | ... | ... |
| CDN/Edge | ... | ... | ... |
| Application | ... | ... | ... |
| DB Query | ... | ... | ... |

## Cache Key Reference

| Resource Type | Key Pattern | Variants | Example |
|--------------|-------------|----------|---------|
| ...          | ...         | ...      | ...     |

## TTL Policy Table

| Resource | Browser max-age | CDN s-maxage | stale-while-revalidate | Rationale |
|----------|----------------|-------------|----------------------|-----------|
| ...      | ...            | ...         | ...                  | ...       |

## Invalidation Flows

### [Resource Type]
1. Mutation occurs in [source]
2. [Event/webhook] triggers cache purge
3. [Layer] invalidates entries matching [pattern]
4. Next request triggers revalidation

## Cache Warming Plan

| Resource | Method | Trigger | Priority |
|----------|--------|---------|----------|
| ...      | ...    | ...     | ...      |

## Cache-Control Headers

| Route Pattern | Cache-Control Value |
|--------------|-------------------|
| ...          | ...               |

Quality Checks

Every cacheable resource has an assigned cache layer and TTL
Cache keys include all variant dimensions (locale, role, version)
Invalidation strategy is defined for every resource that can be mutated
Stale-while-revalidate windows are specified where appropriate
Personalized content is excluded from shared caches (CDN/edge)
Cache warming covers the highest-traffic paths
Cache-Control headers are specified for all route patterns
Cold start scenario is addressed with acceptable latency budgets