Context Window Optimization
TL;DR: Optimizes context window usage through progressive MOAT loading (L1/L2/L3), intelligent pruning, session state management, and token-efficient skill routing. Ensures the AI agent operates within context limits while maintaining access to the knowledge needed for the current task.
Principio Rector
El contexto es un recurso finito. Cargar los 100 skills completos excede cualquier ventana de contexto. La carga progresiva (L1 metadata, L2 core, L3 deep) permite acceder al conocimiento correcto en el momento correcto. La optimización de contexto no es ahorro — es precisión en la información cargada.
Assumptions & Limits
- Assumes skill catalog is indexed with loading level metadata (L1/L2/L3) [PLAN]
- Assumes the lazy-load-resolver script is functional and up to date [SUPUESTO]
- Breaks when context window is too small for even L1 metadata of required skills
- Does not optimize user-provided content — only framework-loaded content
- Session state persistence depends on
project/ directory writability [SUPUESTO]
- Pruning decisions are heuristic — may occasionally remove still-relevant context
Usage
# Optimize context for a specific phase and project type
/pm:context-optimization $PROJECT --phase="planning" --tipo="agile"
# Analyze current context usage and recommend pruning
/pm:context-optimization $PROJECT --type=analyze
# Configure session state persistence rules
/pm:context-optimization $PROJECT --type=session-state --persist="essential"
Parameters:
| Parameter | Required | Description |
|---|
$PROJECT | Yes | Project identifier |
--phase | No | Current pipeline phase for skill selection |
--tipo | No | Project type for routing optimization |
--type | No | analyze, optimize, session-state, prune |
--persist | No | Session persistence level (minimal, essential, full) |
Service Type Routing
{TIPO_PROYECTO}: All project types benefit from context optimization. Complex engagements need L3 for active skills; routine operations use L1/L2.
Before Optimizing
- Read the current session state to understand what is already loaded
- Read the skill catalog to determine which skills are relevant to the current task
- Glob
scripts/lazy-load-resolver.sh to verify resolver availability
- Grep for
project/session-state.json to check current context configuration
Entrada (Input Requirements)
- Current task and phase
- Available context window size
- Skill catalog with loading levels
- Session state
- Previous context usage patterns
Proceso (Protocol)
- Task analysis — Determine which skills are relevant to current task
- Loading level selection — Choose L1 (metadata), L2 (core), or L3 (deep) per skill
- Priority ordering — Load highest-priority skills first
- Session state management — Maintain essential state across interactions
- Pruning strategy — Remove context no longer relevant to current task
- Lazy loading — Load additional context on-demand when referenced
- Compression — Summarize verbose context into essential information
- Cache strategy — Define what to keep in persistent session state
- Monitor usage — Track context consumption per interaction
- Optimization report — Report context efficiency metrics
Edge Cases
- Context overflow despite optimization: Emergency pruning — keep only active skill L2 + session state. Archive other context to
project/context-archive/. Notify user of reduced capability. [PLAN]
- Multiple skills needed simultaneously: Load all at L1 first. Promote to L2 on demand. Only one skill at L3 at a time. Document which skill is in focus. [METRIC]
- Session state lost between interactions: Rebuild from
project/session-state.json. If file missing, re-prime from last known good state. Flag data loss to user. [SUPUESTO]
- User provides massive input exceeding context budget: Summarize user input preserving key facts. Store full input in
project/ for reference. Process in chunks if needed. [PLAN]
Example: Good vs Bad
Good Context Optimization:
| Attribute | Value |
|---|
| Skills loaded | 5 at L1, 2 at L2, 1 at L3 |
| Context utilization | 75% of available window |
| Session state | Essential state persisted in JSON |
| Pruning applied | 3 irrelevant skills removed |
| Lazy loading | 2 skills promoted on demand |
| Efficiency | 40% reduction vs. full loading |
Bad Context Optimization:
Loading all 100 skills at L3 into context, overflowing the window, and producing degraded responses because critical information is truncated. No pruning, no prioritization, no session state management. Fails because it treats context as infinite rather than as a resource to be managed.
Validation Gate
Escalation Triggers
- Critical skill context unavailable due to window limits
- Context overflow causing degraded responses
- Session state loss between interactions
- Loading strategy causing performance issues
Additional Resources
| Resource | When to read | Location |
|---|
| Body of Knowledge | Before optimizing to understand MOAT loading architecture | references/body-of-knowledge.md |
| State of the Art | When evaluating context management approaches | references/state-of-the-art.md |
| Knowledge Graph | To understand skill dependency graph for loading priority | references/knowledge-graph.mmd |
| Use Case Prompts | When configuring optimization for specific workflows | prompts/use-case-prompts.md |
| Metaprompts | To generate context loading configurations | prompts/metaprompts.md |
| Sample Output | To calibrate expected optimization report format | examples/sample-output.md |
Output Configuration
- Language: Spanish (Latin American, business register)
- Evidence: [PLAN], [SCHEDULE], [METRIC], [INFERENCIA], [SUPUESTO], [STAKEHOLDER]
- Branding: #2563EB royal blue, #F59E0B amber (NEVER green), #0F172A dark
Sub-Agents
Context Pruner
Context Pruner Agent
Core Responsibility
Prunes stale or low-priority content from context. This agent operates autonomously, applying systematic analysis and producing structured outputs.
Process
- Gather Inputs. Collect all relevant data, documents, and stakeholder inputs needed for analysis.
- Analyze Context. Assess the project context, methodology, phase, and constraints.
- Apply Framework. Apply the appropriate analytical framework or model.
- Generate Findings. Produce detailed findings with evidence tags and quantified impacts.
- Validate Results. Cross-check findings against related artifacts for consistency.
- Formulate Recommendations. Transform findings into actionable recommendations with owners and timelines.
- Deliver Output. Produce the final structured output with executive summary, analysis, and action items.
Output Format
- Analysis Report — Structured findings with evidence tags and severity ratings.
- Recommendation Register — Actionable items with owners, deadlines, and success criteria.
- Executive Summary — 3-5 bullet point summary for stakeholder communication.
Lazy Resolver
Lazy Resolver Agent
Core Responsibility
Resolves lazy-loaded content on demand. This agent operates autonomously, applying systematic analysis and producing structured outputs.
Process
- Gather Inputs. Collect all relevant data, documents, and stakeholder inputs needed for analysis.
- Analyze Context. Assess the project context, methodology, phase, and constraints.
- Apply Framework. Apply the appropriate analytical framework or model.
- Generate Findings. Produce detailed findings with evidence tags and quantified impacts.
- Validate Results. Cross-check findings against related artifacts for consistency.
- Formulate Recommendations. Transform findings into actionable recommendations with owners and timelines.
- Deliver Output. Produce the final structured output with executive summary, analysis, and action items.
Output Format
- Analysis Report — Structured findings with evidence tags and severity ratings.
- Recommendation Register — Actionable items with owners, deadlines, and success criteria.
- Executive Summary — 3-5 bullet point summary for stakeholder communication.
Progressive Loader
Progressive Loader Agent
Core Responsibility
Implements progressive loading for skill and reference content. This agent operates autonomously, applying systematic analysis and producing structured outputs.
Process
- Gather Inputs. Collect all relevant data, documents, and stakeholder inputs needed for analysis.
- Analyze Context. Assess the project context, methodology, phase, and constraints.
- Apply Framework. Apply the appropriate analytical framework or model.
- Generate Findings. Produce detailed findings with evidence tags and quantified impacts.
- Validate Results. Cross-check findings against related artifacts for consistency.
- Formulate Recommendations. Transform findings into actionable recommendations with owners and timelines.
- Deliver Output. Produce the final structured output with executive summary, analysis, and action items.
Output Format
- Analysis Report — Structured findings with evidence tags and severity ratings.
- Recommendation Register — Actionable items with owners, deadlines, and success criteria.
- Executive Summary — 3-5 bullet point summary for stakeholder communication.
Token Budget Analyzer
Token Budget Analyzer Agent
Core Responsibility
Analyzes context window token usage and optimization opportunities. This agent operates autonomously, applying systematic analysis and producing structured outputs.
Process
- Gather Inputs. Collect all relevant data, documents, and stakeholder inputs needed for analysis.
- Analyze Context. Assess the project context, methodology, phase, and constraints.
- Apply Framework. Apply the appropriate analytical framework or model.
- Generate Findings. Produce detailed findings with evidence tags and quantified impacts.
- Validate Results. Cross-check findings against related artifacts for consistency.
- Formulate Recommendations. Transform findings into actionable recommendations with owners and timelines.
- Deliver Output. Produce the final structured output with executive summary, analysis, and action items.
Output Format
- Analysis Report — Structured findings with evidence tags and severity ratings.
- Recommendation Register — Actionable items with owners, deadlines, and success criteria.
- Executive Summary — 3-5 bullet point summary for stakeholder communication.