context-caching

/context-caching — context-cache discipline (memory-hierarchy borrowing)

Superscalar borrows processor architecture: superscalar issue (§2), out-of-order execution (§2, §5.3), speculation (§4), tier composition (§5.1). This skill adds the memory hierarchy: the prompt cache is the L1 the whole session runs against — reads cost ~0.1× and writes cost 1.25–2×, so the discipline is the same as a CPU's: keep the working set hot, and know exactly which operations flush it.

Normative spec: Superscalar.md §5.4. Volatile facts (vendor multipliers, TTLs, invalidator lists) live in plugins/superscalar/cache-registry.json — dated, source-anchored, with its own revisit cadence. Never recall a number from memory; read the registry, and treat it as expired when its revisit.date has passed.

1. Toggle contract

• State = one marker file: .agent/context-caching.json — {"mode": "self" | "agent" | "off"}. Absent ⇒ off. No mirrors (§5.1's state-convergence lesson).
• /context-caching self|agent|off writes it · /context-caching status reads it back plus the session's cache counters where available.
• Default OFF — modern harnesses already automate the substrate (TTL selection, breakpoint placement, prefix ordering). The skill's jurisdiction is only what the harness does NOT do for you: when to hit a boundary, whether a mutation is worth its flush, and how fan-out changes the accounting. What the harness absorbs over time leaves this skill's scope — that shrinkage is expected, not a defect.

2. self mode — the in-session discipline

1. Pin at the session head. Model and effort are each part of the cache key — switching either mid-session recomputes the entire history. Pick both at the top; a mid-task switch is a paid decision, not a free preference. Need another model for a side question? That is what a subagent is for.
2. Boundary discipline. Compaction rebuilds the conversation layer by design — so choose when: at natural task boundaries, not mid-task via auto-compact. To abandon a path, prefer rewinding to an earlier turn over compacting: a rewind returns to a prefix that is already cached; a compact builds a new one.
3. Prefetch at the boundary. The OS-prefetch analogy: right after a boundary (post-compact, post-clear), load the context the next task will need — the reads land at the front of the new stable prefix and stay cheap for the rest of the task. The wrong time to do bulk reading is right before a boundary, where it is about to be thrown away.
4. Fan-out accounting. A subagent starts cache-cold on its own prefix (and on some harnesses at a shorter TTL), while the parent's cache is untouched. Delegation is therefore cheapest exactly where §5.1 already routes it: self-contained lanes and parallel fan-outs that have forfeited the shared cache anyway. A cache-hot, deep-context single edit loses money on delegation — same rule, cache-side reasoning.
5. Know the flush list. Before any mid-session environment mutation — connecting/disconnecting an MCP server, denying a whole tool, toggling a speed mode — check the registry's invalidator list for the current harness. Some flushes happen without you: a server process dying and reconnecting is a flush on harnesses that load tool definitions into the prefix.
6. Measure, never declare. Cache health is two counters the API already reports (cache-read vs cache-write tokens). High write turn after turn means the prefix is churning — go find what changed. A claimed hit-rate that nobody read from the counters is a declaration, and declarations are how this repository got burned before.