Decision: Block-First Access Pattern (7e-3)

decision-7e3-block-first-access Doc

Project

Decision

7e-3 is not just a hook optimization — it's establishing block-first as the default knowledge access pattern across all agents. The session hook change is one implementation of the pattern, not the whole deliverable.

Key Insight

TOC-based access doesn't reduce what agents read — it changes how they find what to read. The actual token savings come from reading sections instead of full notes. The TOC is navigation; get_section() is the optimization.

This means the convention must be established platform-wide, not just in the session hook. Every agent personality, the agent workflow SOP, and a new convention note all need to encode this pattern.

Decision Rules

Scenario	Tool	Why
Need to know what's in a note	<code>get_note_toc()</code>	Structure only, ~50 tokens
Need one section	<code>get_section(slug, anchor)</code>	Targeted, ~200 tokens
Need the full note (<1K chars)	<code>get_note()</code>	Overhead of TOC+section not worth it for small notes
Update one section	<code>update_block(slug, anchor, content)</code>	Surgical, no full rewrite
Rewrite most of a note	<code>update_note(content=...)</code>	Block tools inefficient for full rewrites
Create a new note	<code>create_note()</code>	Blocks auto-generated from HTML (7e-1)

The rule: start narrow, widen if needed. TOC first. Section if relevant. Full note only if you need most of it.

Scope of 7e-3

Four deliverables:

Convention note (convention-block-first-access) — document the pattern and decision rules
Session hook (session-start-context.sh) — inject plan TOCs, lazy loading instructions
Agent personality updates (agent-betty-sue, agent-dottie) — encode block-first in operating instructions
SOP update (agent-workflow) — add block-first as part of the operating model

What Stays Unchanged

Personality injection (agent-betty-sue full text) — needs full content to define behavior, ~500 tokens, not the bottleneck
SOP list — already compact metadata (title + slug only)
Core SOP full reads (agent-spawn-conventions, agent-workflow) — small notes, ~1K each, frequently referenced
Small notes (<1K chars) — block overhead not worth it