Instruction-Bearing Content Routing
Learning Headroom
From Layout to Routing: A New Decision
Recall (2.3): stable prefix stays byte-identical, live zone can change.
Recall (5.1): specialized compressors preserve structure while shrinking size.
**New question:** inside the live zone's wake digest, which *fields* can shrink, and which cannot lose a single word?
**The core boundary:**
- Instruction-bearing fields → stay **verbatim**, or get a verbatim summary + retrievable detail
- Everything else → compact summary is fine
- CCR-backed content is *backing detail*, never the instruction itself
```mermaid
flowchart TD
A["Wake digest field"] --> B{"Does it carry instructions or acceptance criteria?"}
B -->|Yes| C["Verbatim"]
B -->|No, but high-stakes| D["Verbatim summary plus retrievable backing detail"]
B -->|No, informational| E["Compact summary, optionally CCR-backed"]
```
The Digest Routing Table
| Field | Handling | Why |
|---|---|---|
| Current task | **Verbatim** | Instruction-bearing, drives the next action |
| Hard constraints | **Verbatim** | Safety / acceptance boundaries |
| Definition of done | **Verbatim** | Wording must survive every wake intact |
| Irreversible decisions | Verbatim summary + retrievable backing detail | Summary short, detail exact |
| Open threads | Compact summary + CCR-backed detail | Thread shrinks, source stays recoverable |
| Learnings | Compact summary | Informs future action, exact prose not needed |
| File/search/tool outputs | CCR-backed compression | Large backing detail, must stay retrievable |
**Why verbatim for the top three?** Change one word in a hard constraint or a definition of done, and the agent's *acceptance criteria* silently changes — a paraphrase can flip meaning without anyone noticing.
Worked Example: Routing a Real Wake Digest
**Given** this raw wake digest content:
1. Current task: "Fix the pagination bug in /api/orders so page 2+ returns correct totals."
2. Hard constraint: "Never write to the orders table outside a transaction."
3. Definition of done: "All existing tests pass AND a new regression test for page 2 totals is added."
4. Irreversible decision: "Team decided on 2024-03-01 to drop the legacy v1 orders endpoint after a 400-line discussion of tradeoffs."
5. Open thread: "Investigating whether the totals bug also affects the /api/invoices endpoint — 3 messages, still unresolved."
6. Tool output: a 2,200-token JSON dump from a database query.
**Routed result — step by step:**
1. → **Verbatim**, unchanged. It's the current task: an active instruction driving the next action.
2. → **Verbatim**, unchanged. It's a hard constraint: a safety boundary, not a suggestion.
3. → **Verbatim**, unchanged. It's the definition of done: the exact acceptance wording.
4. → Reduce the 400-line discussion to its outcome: "2024-03-01: dropped legacy v1 orders endpoint" (a verbatim-style summary — short but precise) **+** the full 400-line discussion stored, retrievable via `headroom_retrieve`.
5. → Reduce the 3 messages to their gist: "Checking if totals bug hits /api/invoices too (unresolved)" **+** the original 3 messages kept as CCR-backed detail.
6. → The 2,200-token JSON payload is replaced with a CCR-backed compressed stand-in; the original JSON is recoverable on demand.
Why Backing Detail Is Not the Instruction
**Key distinction:** CCR-backed content is *backing detail*, never the instruction itself.
Mechanics that keep routing honest:
- `headroom_retrieve` — recovers the original from the local store on demand
- `HEADROOM_CCR_TTL_SECONDS` — sizes how long the local store keeps that original
- `compression_strategy` — the **authoritative** metadata tag identifying how a stored entry was produced
**Rule:** never infer routing from payload *shape* (e.g. "it looks like JSON so it must be safe to compress"). Use the stored `compression_strategy` metadata instead.
**On expiry:** if `HEADROOM_CCR_TTL_SECONDS` runs out before retrieval, regenerate the digest or re-read the source — don't guess.
```mermaid
flowchart LR
S["Stored CCR entry"] -->|compression_strategy tag| R{"Routing decision"}
R -->|instruction-bearing| V["Keep verbatim upstream"]
R -->|backing detail| C["Compact plus retrievable"]
T["TTL expires"] --> X["Regenerate digest or re-read source"]
```
Common Failure: Compressing an Instruction by Mistake
**Wrong routing (compresses a hard constraint):**
Original: "Hard constraint: Never write to the orders table outside a transaction."
Bad compact summary: "Constraint: be careful with orders table writes."
→ Lost the word *transaction*. Lost the word *never*. The rule became a suggestion.
**Correct routing:**
Same text kept **verbatim**, in full, every wake — no summarizer touches it.
**General rule of thumb:**
\[
\text{field} \in \{\text{task},\ \text{constraint},\ \text{definition of done}\} \;\Rightarrow\; \text{no compressor runs on it at all}
\]
Even the specialized compressors from 5.1 must skip these fields entirely — routing decides *before* compression is attempted.
Where This Fits: Toward a Full Digest Strategy
**Recap of the routing map:**
```mermaid
flowchart TD
Task["Current task"] --> V1["Verbatim"]
HC["Hard constraints"] --> V1
DoD["Definition of done"] --> V1
Irr["Irreversible decisions"] --> S1["Verbatim summary plus retrievable detail"]
Open["Open threads"] --> S2["Compact summary plus CCR-backed detail"]
Learn["Learnings"] --> C1["Compact summary"]
Tool["Tool, file, search outputs"] --> C2["CCR-backed compression"]
```
**Builds on ←** 2.3 (stable prefix vs. live zone) and 5.1 (specialized compressors) — routing is the decision layer that tells those compressors where they're allowed to run.
**Where this leads →** 7.1, *Designing a Repeated-Wake Digest Strategy*, assembles this exact routing map into a full end-to-end digest policy — this node is the field-level rule set that policy is built from.
Back to course