caching-strategy

Caching Strategy

capability: architecture
domain: cross-cutting
state: experimental
dependencies:
  - nfr-definition
  - observability
triggers:
  - "a read path is slow and caching is being considered"
  - "introducing a new cache layer or cache-aside pattern"
  - "designing cache invalidation for a data type"
  - "diagnosing stale-data or cache-stampede incidents"
  - "defining the staleness budget for a cached value"
outputs:
  - caching decision record (cache vs. fix-the-query, with rationale)
  - cache layer + invalidation strategy per data type
  - key design + namespacing convention
  - staleness budget tied to the relevant NFR
  - cache hit-ratio SLI + alert thresholds
consumers:
  - backend-developer (implements the cache-aside/write-through logic)
  - frontend-developer (implements client-side and CDN cache headers)
  - platform-sre (owns distributed cache infrastructure and capacity)
  - observability (receives hit-ratio and staleness metrics)
references: []

Caching trades correctness (a cache can lie) for speed. That trade is only worth making deliberately, per data type, with an explicit invalidation strategy and a staleness budget — not reflexively bolted onto every slow endpoint.

When this skill fires

• A read path is slow and caching is proposed as the fix.
• A new cache layer (in-process, Redis/Memcached, CDN) is being introduced.
• Cache invalidation for a data type is being designed or is producing stale-data bugs.
• An incident involves a cache stampede, unbounded cache growth, or serving stale data past its acceptable window.
• The staleness budget for a cached value needs to be tied to its NFR.

Step 1: should this be cached at all?

Before choosing a strategy, rule out that caching is masking a fixable problem:

• Is the query itself the bottleneck? Missing index, N+1 query, unbounded result set, chatty round-trips — fix these first. A cache in front of a bad query hides the problem until the cache misses (cold start, invalidation, capacity eviction) and the bad query hits full traffic anyway.
• Is this data cheap to compute correctly on every request? If so, caching adds invalidation risk for marginal gain — don't.
• Does correctness matter more than latency here? Financial balances, permission checks, inventory counts at checkout — these need care; caching them requires an explicit staleness budget signed off against the NFR, not a default TTL picked without thought.