assembling-context

name	assembling-context
description	Use when preparing context for subagent dispatch or managing token budgets. Triggers: 'prepare context for', 'assemble context', 'token budget', 'context package', 'what context does the subagent need'. Also invoked by develop during planning and execution phases.

Context Assembly

Context Curator. Deliver precisely the right information at the right time. Too little causes failures. Too much burns tokens and buries signal. Every token must earn its place.

Invariant Principles

1. Tier 1 Never Truncates: Essential context survives any budget pressure
2. Budget Before Assembly: Calculate budget FIRST, then select
3. Purpose Drives Selection: Design context differs from implementation differs from review
4. Recency Over Completeness: Recent feedback beats historical context
5. Summarize, Don't Truncate: Intelligent summarization preserves signal
6. Integration Points are Tier 1: Interface contracts are essential

Inputs / Outputs

Input	Required	Description
purpose	Yes	design, implementation, review, handoff, subagent
token_budget	Yes	Maximum tokens available
source_context	Yes	Raw context to select from

Output	Description
context_package	Tiered context ready for injection
truncation_report	What was excluded and why

Context Tiers

Over budget: remove Tier 3 first, then Tier 2. Never remove Tier 1.

Tier	Budget	Content	Examples
1: Essential	40-60%	Active instructions, user decisions, current artifact, interface contracts, blocking issues	Task spec, APIs, unresolved feedback
2: Supporting	20-35%	Recent learnings, patterns, prior feedback, success criteria	Last 2-3 iterations, codebase patterns
3: Reference	10-20%	Historical context, rejected alternatives, verbose docs	Early iterations, full docs (summarize instead)

Purpose-Specific Packages

Purpose	Tier 1 Focus	Budget Split	Use With
Design	Requirements, decisions, constraints, integration points	50/30/20	design-exploration, writing-plans
Implementation	Task spec, acceptance criteria, interfaces, test expectations	60/25/15	test-driven-development, executing-plans
Review	Code diff, requirements traced, test results	55/30/15	code-review, fact-checking
Handoff	Current position, pending work, active decisions, blocking issues	70/20/10	session boundaries, compaction
Subagent	Task, constraints, expected output format	65/25/10	dispatching-parallel-agents

Token Budget

Estimation: tokens ≈ chars / 4 (conservative)

Available: context_window - system_prompt - response_reserve - tool_overhead Example: 200000 - 8000 - 4000 - 2000 = 186000

Smart Truncation: Never blind head/tail. Preserve structure: intro (30%) + conclusion (20%), mark omitted middle.

Cross-Session Context

Action	Items
Persist	User decisions, validated assumptions, glossary, blocking issues
Regenerate	File contents, test results, code patterns (may have changed)
Discard	Exploration paths, rejected alternatives, verbose logs

Handoff format: Position → Pending work → Active decisions → Key learnings → Verification commands

Reasoning Schema

Before assembling: PURPOSE? TOKEN BUDGET? TIER 1 for this purpose? RECIPIENT? After assembling: Tier 1 fits? Essential excluded? Room for Tier 2? Truncation report accurate? - Assembling without calculating budget first - Blind truncation (`head`, `tail -n`, arbitrary limits) - Truncating Tier 1 to fit budget - Same package for different purposes - Omitting integration points - Including exploration paths in handoff - Persisting raw command output across sessions

Self-Check

• Calculated token budget explicitly
• Identified Tier 1 for this purpose
• Tier 1 fits within budget
• Smart truncation applied (not blind)
• Integration points included
• Truncation report created

<FINAL_EMPHASIS> Context assembly is invisible infrastructure. Calculate budget. Prioritize by tier. Truncate intelligently. Every token earns its place. </FINAL_EMPHASIS>