# Add caching at one boundary, with clear rules for clearing it

A cache designed with its clearing rules from the start, rather than added after somebody notices out-of-date data.

Category: Performance and cost
Source: https://letsship.ai/use-cases/add-caching-with-explicit-invalidation
Published: 2026-08-25

## Goal

Add a cache at one boundary, with explicit invalidation and tests for every path.

## Acceptance criteria

- Hit, miss, and invalidation each have a test
- The invalidation trigger is explicit rather than time-based alone
- Cached data carries no per-user content unless the key includes the user
- Hit rate is measurable after deploy

## What lands as proof

Tests for all three paths, especially invalidation, which is the one that causes the incidents.

## Prompt

Copy this to an agent to open the ticket:

```text
Create a Linear issue in my team and assign it to the SHIP agent.

Title: Add caching at {boundary}

Description: Add a cache at one boundary, with explicit invalidation and tests for every path.

Acceptance criteria:
- Hit, miss, and invalidation each have a test
- The invalidation trigger is explicit rather than time-based alone
- Cached data carries no per-user content unless the key includes the user
- Hit rate is measurable after deploy

Before you create the issue, find an expensive repeated read in this repository and replace {boundary} with it. Name what should invalidate it.
```

## Questions

### What does the agent actually change?

The ticket is scoped to one outcome: add a cache at one boundary, with explicit invalidation and tests for every path. Work that serves that outcome is in scope, and anything outside it is left for a separate ticket, so the pull request stays reviewable.

### How do I know the work is done?

The pull request carries the evidence, not only the diff. Here that means hit, miss, and invalidation all covered by tests, so a reviewer can confirm the result without reproducing the work locally.

### How much oversight does this need?

The run stops once the plan is written. Somebody reads the approach and approves it before any code exists, which is the cheapest moment to redirect the work.