Prompt-Cache-Aware Conversation Design

PROJECT CONTEXT:
My agent's API bills and latency grow with every turn because each call re-processes the whole context. Provider prompt caching can cut both dramatically - but only if the context is laid out so prefixes stay byte-stable.

GOAL:
Restructure context assembly for maximum cache hits: stable-first ordering, append-only history, and isolation of volatile content.

REQUIREMENTS:
- Context ordered stable-first: system prompt, tool definitions, then history, then volatile state
- History strictly append-only between compactions - no in-place edits to old turns
- Volatile content (timestamps, usage counters) moved out of the cached prefix
- Cache breakpoints/markers applied per provider requirements
- Before/after measurement of cached vs uncached token ratios

CONSTRAINTS:
- Never sacrifice correctness for cache hits - compaction still wins when needed
- Cache behavior must be verified from API response metadata, not assumed

DEFINITION OF DONE:
- Multi-turn sessions show high cached-token ratios in API metadata after turn 1
- No per-turn mutation of the system prompt or old history remains
- Cost per turn measurably drops versus the pre-optimization baseline
- Compaction and cache design coexist: cache resets at compaction are accepted and logged

COMMON FAILURES TO AVOID:
- A timestamp in the system prompt silently killing the cache every turn
- Re-sorting or rewriting history each call so no prefix ever matches
- Injecting the dynamic plan reminder at the top instead of the tail
- Claiming cache wins without reading the usage fields that prove them