athola/context-optimization

Table of Contents

• When to Use
• Core Hub Responsibilities
• Module Selection Strategy
• Context Classification
• Integration Points
• Resources

Context Optimization Hub

When To Use

• Threshold Alert: When context usage approaches 50% of the window.
• Complex Tasks: For operations requiring multi-file analysis or long tool chains.

When NOT To Use

• Simple single-step tasks with low context usage
• Already using mcp-code-execution for tool chains

Core Hub Responsibilities

1. Assess context pressure and MECW compliance.
2. Route to appropriate specialized modules.
3. Coordinate subagent-based workflows.
4. Manage token budget allocation across modules.
5. Synthesize results from modular execution.

Module Selection Strategy

def select_optimal_modules(context_situation, task_complexity):
    if context_situation == "CRITICAL":
        return ['mecw-assessment', 'subagent-coordination']
    elif task_complexity == 'high':
        return ['mecw-principles', 'subagent-coordination']
    else:
        return ['mecw-assessment']

Context Classification

| Utilization | Status | Action | |-------------|--------|--------| | < 30% | LOW | Continue normally | | 30-50% | MODERATE | Monitor, apply principles | | > 50% | CRITICAL | Immediate optimization required |

Large Output Handling (Claude Code 2.1.2+)

Behavior Change: Large bash command and tool outputs are saved to disk instead of being truncated; file references are provided for access.

Impact on Context Optimization

| Scenario | Before 2.1.2 | After 2.1.2 | |----------|--------------|-------------| | Large test output | Truncated, partial data | Full output via file reference | | Verbose build logs | Lost after 30K chars | Complete, accessible on-demand | | Context pressure | Less from truncation | Same - only loaded when read |

Best Practices

• Avoid pre-emptive reads: Large outputs are referenced, not automatically loaded into context.
• Read selectively: Use head, tail, or grep on file references.
• Use full data: Quality gates can access complete test results via files.
• Monitor growth: File references are small, but reading the full files adds to context.

Integration Points

• Token Conservation: Receives usage strategies, returns MECW-compliant optimizations.
• CPU/GPU Performance: Aligns context optimization with resource constraints.
• MCP Code Execution: Delegates complex patterns to specialized MCP modules.

Resources

• MECW Theory: See modules/mecw-principles.md for core concepts, the 50% rule, and quick-start code examples.
• Context Analysis: See modules/mecw-assessment.md for risk identification.
• Workflow Delegation: See modules/subagent-coordination.md for decomposition patterns.
• Context Waiting: See modules/context-waiting.md for deferred loading strategies.
• Cache Alignment: See modules/cache-aligned-prefixes.md for ordering context so provider KV caches hit (stable prefix first, volatile last).

Troubleshooting

Common Issues

If context usage remains high after optimization, check for large files that were read entirely rather than selectively. If MECW assessments fail, ensure that your environment provides accurate token count metadata. For permission errors when writing output logs to /tmp, verify that the project's temporary directory is writable.

Exit Criteria

• [ ] Context pressure assessed against the MECW 50% rule
• [ ] A memory tier or routing decision recorded for the current state
• [ ] Large outputs referenced by file or handle, not read in full
• [ ] When the request controls the provider payload, prefix ordering checked against modules/cache-aligned-prefixes.md (stable first, volatile last)
• [ ] Optimization downgraded to advisory when the harness already caches (cache writes cost more than they save on non-repeated prefixes)