Cache Strategy

---
name: cache-strategy
description: |
  Trigger when the user asks to add caching, speed up slow queries, reduce
  load, or pick a cache strategy. Phrases: "add caching", "cache layer",
  "Redis cache", "stale-while-revalidate", "query cache".
allowed-tools:
  - Read
  - Write
  - Edit
  - Grep
---

# Cache Strategy

Design a caching layer for a web app. Pick the right strategy per data class,
handle invalidation, and avoid the three-kinds-of-stale bug.

## Prerequisites

- Slow path identified with measurements (not guesses)
- Redis or equivalent available for shared cache, or Next.js for edge cache

## Steps

1. **Classify the data by volatility:**
   - **Immutable** (blog post markdown, uploaded images) - cache aggressively, invalidate on deploy
   - **Slow-changing** (user profile, product catalog) - stale-while-revalidate with minutes TTL
   - **Fast-changing** (current cart, live counts) - cache for seconds or not at all
   - **Per-user** (notification count) - cache in session, not shared Redis

2. **Pick the strategy per class:**
   - Immutable -> CDN or build-time generation
   - Slow-changing -> Redis with `GET` then `SET EX`, or SWR pattern
   - Fast-changing -> skip caching, optimize the query instead
   - Per-user -> in-process LRU keyed by user ID

3. **Next.js App Router specific:**
   ```ts
   // Per-request memoization (free, just enable)
   import { cache } from "react";
   const getUser = cache(async (id) => { ... });

   // Revalidation for dynamic data
   await fetch(url, { next: { revalidate: 60 } });

   // On-demand invalidation
   import { revalidateTag } from "next/cache";
   revalidateTag("user-profile");
   ```

4. **Invalidation strategy.** Caches fail in three ways:
   - **Too long** - users see stale data
   - **Too short** - cache does nothing
   - **Never invalidated** - stale forever after mutation

   For every cached read, identify what writes to the same data and wire
   the invalidation.

5. **Never put PII in a shared cache** without deliberate design. Cache key
   collisions between users are a data-leak bug.

## Anti-patterns

- Caching the whole DB row when you only read one field
- Setting TTL by instinct instead of data volatility
- Adding a cache to "make it faster" without measuring
- Caching at two layers (Redis + CDN) with conflicting TTLs

## Output

- Cache strategy documented per data class in the README
- Redis keys namespaced (`user:{id}:profile` not `user_1234`)
- Invalidation paths wired for mutations
- Before/after latency measurements