Module 2 · Tools, Knowledge, Memory & Research Design · scripted

Abstraction: Briefing in Apples

25 minoutcomes: context-engineering, agent-architectures

Two compactions of the same history

The compaction move we just built produced a record: what was done, what was decided, what remains. For many tasks that is exactly right. But watch a case where it quietly isn't. A coding agent has spent 60 iterations building a sensor-data ingestion service — designing, writing, refactoring, fixing. The wall is full. Two different summarizers compact the same history:

Compaction A · the record

BRIEFING: Built ingestion for the buoy network. Iterations 1–14: set up project, chose Postgres. 15–31: wrote CSV import for the wave-height sensors, fixed timestamp bugs. 32–44: added the JSON feed for the weather buoys; refactored shared parsing. 45–60: validation added after bad readings crashed the store; parsing moved out of the API layer. REMAINING: support the new acoustic sensors (binary format).

Compaction B · the model

Compaction B · the invariants

ARCHITECTURE:adapter pipeline (see diagram). · One adapter per sensor format. Formats touch NOTHING but their adapter. · Only the normalizer writes to the store. The API only reads. · All readings pass the validator — no exceptions, that rule is written in blood (iterations 45–60).
REMAINING:acoustic sensors (binary format) → write adapter #3.

Both are honest. Both fit on one page. Now give each briefed agent the same next task and watch the difference:

Example 1a · Continuing from the record
user

Add support for the acoustic sensors — binary format, spec attached.

assistant
⟨tool_use⟩
edit_file(path = "api/handlers.py", old = "…", new = "def
receive_acoustic(payload): readings = parse_binary(payload);
db.insert(readings)")
NoteLocally reasonable — parse the bytes, store the readings. But it parses in the API layer and writes directly to the store: the two exact mistakes iterations 45–60 spent their budget undoing. The record even mentions those repairs — as history. Nothing on the wall says they are law.
Example 1b · Continuing from the model
user

Add support for the acoustic sensors — binary format, spec attached.

assistant
⟨tool_use⟩
create_file(path = "adapters/acoustic.py", content = "# adapter #3:
binary → readings, emits to validator …")
assistant

I've added the acoustic adapter following the pipeline: it parses the binary format and emits standard readings to the validator — nothing else touches the new format, and the store still has a single writer.

NoteSame model, same task, same page-sized briefing. But this wall holds a structure, and self-conditioning — which we've usually treated as a hazard — is now doing the governing: every line the agent writes is a continuation of the architecture, because the architecture is the loudest thing on its wall.

Record vs. model

A RECORD is organized by the past: what happened, in order.
A MODEL is organized by the domain: how to think about what's next.

A record INFORMS the remaining work.
A model GOVERNS it.

The second framing

Name what Compaction B really did: it changed the representation. We learned earlier that the description chooses the solution — polar coordinates make the circle easy — and that the first framing is chosen before the conversation begins. Compaction is the one moment in a trajectory where you get to choose the coordinate system again, and this time with the benefit of everything the conversation has learned. Sixty iterations ago, nobody knew the architecture. Now it's known — and the compacted wall can be built out of it.

The second framing

Compaction doesn't have to shrink the old representation.
It can REPLACE it — with the representation the remaining
work deserves, chosen in hindsight.

Write the briefing in apples

Now the second move, and it reaches back to the beginning of our tool-design work. Recall the word apple: one small token, and an information-dense structure unfolds — looks, weight, uses — learned long before the conversation began. We used that to price tool names. But the same economics govern every word on the wall, including every word of a briefing. Compare two ways to convey the same architecture:

The same knowledge, priced two ways

IN EPLES (described from scratch) ~95 tokens "The system is organized so that business logic never touches the database directly; instead, access goes through objects that expose collection-like operations, and the core logic is kept independent of the web framework and storage so each can be swapped; state changes are captured as a sequence of events rather than updates in place…"

IN APPLES (named) ~14 tokens "Hexagonal architecture. Event-sourced. Repository pattern — no ORM types outside the repositories."

…and the named version is BETTER, not just cheaper: each name unfolds into more trained structure than the paragraph managed to describe — edge cases, conventions, standard mistakes included. The description is a translation bill. The name is a paid-up account.

The design rule for every abstraction you write:

The apple principle, generalized

The best compression is a pointer into what the model
already knows.

Write the briefing in apples, not in eples: name every
pattern that HAS a name, and spend description only on
what is genuinely novel.

The engineered apple

What about structures that have no standard name? Then you choose an apple to borrow: a metaphor. A good metaphor imports a whole trained bundle of entailments in a handful of words. Watch one do real reasoning work:

Example 2 · The coat check
user

Our results cache works like this — it's in your briefing: "the cache is a coat check: storing returns a ticket; retrieval requires the ticket; the cloakroom is small." A user reports their report link failed with "result not found" after lunch. What happened, and what should the retry logic do?

assistant

The cloakroom is small — coats get cleared out to make room when new ones arrive. The user's result was evicted while they were at lunch; their ticket is valid but the coat is gone. Retry logic: never treat the ticket as a guarantee. On "not found," regenerate the result, store it again, and hand back the new ticket — and for anything a user might return to hours later, persist it properly instead of leaving it at the coat check.

NoteNobody stated an eviction policy, TTLs, or regenerate-on-miss. The agent derived all of it from six words of metaphor — the way the orchard agent derived throwing from apple. A metaphor is an engineered apple: you pick which trained structure to borrow, and its entailments come packed inside.

Apples decompress more than you asked for

And that is also the danger. The thrown apple came with affordances nobody stated — that was the magic — but wrong names ship wrong affordances with exactly the same silence. Call your buffer a "queue" and the model assumes first-in-first-out; if it isn't, you have re-created the lying name — this time in your briefing instead of your tool set. The disciplined pattern is the one experts use on each other:

Name, then deviate

RISKY:"the job queue" (…it isn't FIFO)
DISCIPLINED:"the job pool — like a queue, except workers take the highest-priority job, not the oldest"

The name pays for 95% of the structure. The exception clause costs one line. Never let the name promise something the system doesn't keep.

Borrowed structure, audited
  • In Example 2, list three entailments of "coat check" that are true of the cache — and invent one that could be false. What would the agent do wrong because of it?
  • What's the "coat check" of your own research domain — the metaphor your field uses to brief newcomers in one line? What does it get slightly wrong?

The three registers

Step back, because this completes a ladder we started building back with the Tolstoy manual. There are three registers for putting knowledge into a conversation, in increasing order of density:

Describe · exhibit · point

DESCRIBErules and definitions. Leaks at every edge; pay for every word. (The Tolstoy manual, vol. 1 of 14.)
EXHIBITexamples. Dense; edges included free. (Hand them Anna Karenina.)
POINTnames and metaphors. Densest of all — but only for patterns already in the weights. ("Write like Tolstoy." Three words — which work only because Tolstoy is in the weights.)

Choosing a register is a lookup question: is this pattern trained? Point at it. Merely demonstrable? Exhibit it. Genuinely novel? Then you must describe it — and pay full price. A well-built abstraction usually uses all three: names for the known patterns, one worked example for the house style, description only for the truly local rules. That mix — not any single register — is what makes a one-page briefing able to stand in for sixty iterations.

What abstraction is

Compaction asks:   what can we DROP?
Abstraction asks:  what can we POINT TO instead of carry?

The lightest context is not a shorter transcript.
It is a better representation — written in words that
were paid for during training, not during the task.
Your turn

Return to the compaction you built in the earlier fork — and redo it as an abstraction. (1) Choose the representation the remaining work deserves: a diagram, a schema, a set of invariants — not a timeline. (2) Name every nameable pattern in it; count the tokens you just stopped paying. (3) Engineer one metaphor for a structure with no standard name — and write its deviation clause. (4) Run both briefings on the same next task and compare what each agent built: which one's work is cohesive with everything that came before?