Context Economics

The constraint

An LLM agent operates inside a fixed context window. Every file read, every rule injection, every hook output consumes tokens. A session that loads the entire repository on startup will exhaust context before writing code. A session that loads nothing will violate architecture constraints.

Context economics is the engineering discipline of loading the right information at the right time — no sooner, no later.

---

Hydration scope

Session start loads a bounded set. Defined in .sdlc/INDEX.md [HYDRATION_SCOPE]:

Eager (sessionStart and /hydrate-context):

Section	Content
ACTIVE_WORK	Current tickets, runs, stages
SPECS	Approved specification paths
ADRS	Decision record index
RUNTIME.COMMANDS	Slash command registry
RUNTIME.SKILLS	Skill registry
ENTRY_POINTS	Top-level navigation pointers

Lazy (on demand only):

Content	Access path
Playbook catalog	python3 .sdlc/bin/sdlc_playbook.py catalog --summary
Domain playbooks	resolve + provision at workflow stage
Playbook research artifacts	.sdlc/playbooks/.research/{run_id}/
Full PLAYBOOKS.md	Never in sessionStart

Forbidden on hydrate:

• .sdlc/playbooks/domains/** (bulk)
• .sdlc/playbooks/.research/**
• Full playbook catalog read

Rule: agents must NOT load playbook catalog during sessionStart or hydrate-context.

---

Why lazy playbooks

A playbook for Three.js modeling may be 2,000 tokens. A playbook for DOCX generation may be 1,500 tokens. Loading all playbooks at session start consumes context that 95% of sessions will never use.

Instead:

1. Session start loads SDLC infrastructure (rules, memories, handoff).
2. When a workflow stage declares playbooks_when: or a spec carries domain_tags, runtime calls provision.
3. Only then does the relevant playbook enter context.

Trade-off: first invocation of a domain capability pays a provision latency cost. Benefit: baseline session token budget stays predictable.

---

Always-applied rules cost

Rules in {specialization_layer}/rules/ inject on every agent turn. Typical categories:

• Architecture constraints
• Output standards
• Dependency gates (when package manifests exist)
• Stack-specific patterns (added at init based on profile)

/sdlc:token-health audits this corpus. Report artifacts:

• .sdlc/sdlc-token-health.html
• canvases/sdlc-token-health.canvas.tsx

Measured always-injected baseline: ~9,426 raw tokens (as of last audit in INDEX).

Design principle: if knowledge applies to every turn, it belongs in rules or memories. If it applies to one domain, it belongs in a playbook.

---

Memories vs INDEX vs specs

Three documentation layers with different load profiles:

Layer	Size	Load when	Update when
Memories	Small (~200 lines each)	Every session (hook)	Event-driven
INDEX	Medium (bracket notation)	Hydrate (scoped sections)	New doc created
Specs	Large (per feature)	Feature start only	Spec approval

An agent implementing JAMBU-33 reads the JAMBU-33 spec — not all specs in .sdlc/specs/. INDEX tells the agent the spec exists; the spec file provides detail.

---

Handoff as compression

A handoff (.sdlc/handoffs/LATEST.md) is lossy compression of session state:

• What was accomplished
• What remains open
• Active worktree paths
• Blockers and gate status

The next session reads the handoff instead of re-deriving state from git log, ticket comments, and manifest YAML. This is cheaper than re-exploration and more reliable than chat transcript history.

Stub handoffs fail mark-done gate — they indicate the compression step was skipped.

---

Bracket notation INDEX

.sdlc/INDEX.md uses bracket notation ([SECTION], key→value|pipe) for token efficiency. Agents parse structured sections without reading prose navigation.

Example:

[ACTIVE_WORK]
JAMBU-34 ticket=SDLC_gate_matrix spec=.sdlc/specs/infra-sdlc-gates-hardening.md stage=execution
[/ACTIVE_WORK]

Trade-off: human readability is reduced. Benefit: INDEX fits in fewer tokens and supports deterministic section extraction in hooks.

---

Cognitive trace

Hook handler collects agent events to .sdlc/trace/events.jsonl. Trace UI (ai-native-sdlc trace) provides SSE stream at /api/events/stream.

Trace is observability for the cognitive layer — not input to agents. It does not consume session context. It answers: what did the agent read, edit, and execute?

Session start surfaces trace dashboard URL when server is running.

---

Token-health remediation

/sdlc:token-health --fix applies bracket-notation compression to eligible corpus files. This is a maintenance operation, not runtime behavior.

Compression targets:

• Verbose prose in INDEX sections
• Redundant cross-references
• Duplicate constraint declarations across rules and memories

Constraint: compression must not remove enforceable content — only redundant expression.

---

Design rules for new artifacts

When adding documentation or procedures:

1. Does every session need this? → memory or rule
2. Does one feature need this? → spec
3. Does one domain need this, sometimes? → playbook (lazy)
4. Does one workflow stage need this? → command or workflow stage input
5. Is this navigation metadata? → INDEX entry (scoped section)

Violating these rules inflates baseline context and degrades agent performance across all sessions — not just the feature that introduced the bloat.

---

Operational consequences

Hydration scope is a contract. Expanding eager scope requires justification in an ADR and token-health re-audit.

Lazy loading has a cold-start cost. First /sdlc:learn or playbook provision in a session reads files that eager hydration deliberately excluded.

Rules are expensive. Adding a new always-applied rule affects every turn of every session. Prefer playbook or skill unless the constraint is truly universal.

Handoffs are mandatory compression. Sessions that skip handoff force the next session to pay rediscovery cost — or fail gates if the run attempts closure.