caching

name	caching
description	Use when creating, updating, reviewing, or debugging caching, cache keys, TTL, invalidation, Redis, in-memory cache, CDN cache, performance, stale data, or cache-related bugs.

Caching

Use this skill for safe caching that improves performance without breaking correctness.

Rules

• Follow the project’s existing caching pattern.
• Do not add a new cache provider or caching library unless already used or explicitly requested.
• Cache only data that is safe and useful to cache.
• Define TTL, invalidation, or both.
• Prefer correctness over speed.
• Cache failures should not break the main flow unless cache is the source of truth.
• Do not cache passwords, secrets, raw tokens, payment details, or highly sensitive data.
• Do not leak data between users, organizations, or tenants through shared cache keys.
• Preserve existing logging, error, and test patterns.
• Avoid unrelated refactors.

Inspect First

Before changing cache behavior, check existing patterns for:

• cache provider/helper
• cache key naming
• TTL conventions
• invalidation strategy
• user/org/tenant scoping
• fallback behavior
• logging
• tests

Implementation Checklist

• Identify the source of truth.
• Decide what should be cached.
• Reuse existing cache helpers.
• Design deterministic cache keys.
• Include user, organization, tenant, locale, filters, pagination, or feature flags when they affect results.
• Add explicit TTL unless reliable invalidation already exists.
• Add invalidation for create/update/delete or permission changes.
• Add safe fallback for cache read/write failure.
• Add or update relevant tests.

Cache Key Rules

• Use deterministic, namespaced keys.
• Include scope for user, organization, tenant, or permission-sensitive data.
• Include filters, pagination, locale, currency, and variants when relevant.
• Avoid raw untrusted input without normalization.
• Avoid keys that can collide across users or contexts.
• Version keys when cached data shape can change.

TTL and Invalidation Rules

• Use short TTLs for frequently changing or permission-sensitive data.
• Use longer TTLs only for stable data.
• Avoid indefinite caching unless invalidation is reliable.
• Invalidate affected detail and list caches after mutations.
• Invalidate permission-sensitive caches after role or membership changes.
• Prefer targeted invalidation over broad cache clearing.
• Make invalidation safe to retry.

Safety Rules

• Never cache plain passwords, raw secrets, full payment details, or private data in a shared key.
• Do not cache authorization decisions unless short-lived and safely scoped.
• Do not log sensitive cached values.
• Treat cached data as potentially stale.
• Do not serve stale data for security, billing, permission, or ownership decisions.

Failure Handling

• Cache read failure: load from source of truth when possible.
• Cache write failure: continue main request when safe.
• Cache invalidation failure: log or surface the risk according to project pattern.
• Cache required for correctness: fail safely and explicitly.
• Avoid cache stampedes using existing lock/dedupe/coalescing patterns when available.

Tests

Cover relevant paths:

• cache hit
• cache miss
• cache write
• cache read/write failure
• invalidation after mutation
• scoped cache keys
• stale data prevention
• permission or ownership boundary when relevant