Bruno-Cunha-Souza/ValarMindSkills / skills/context-optimization
context-optimization
UnverifiedLifecycle context audit/optimize/plan. Audit mode (Phase 0..6) + Guide mode (catalog lookup). Targets long-conv agents, RAG pipelines, sub-agents, large-doc workflows. Detects bloat/dedup/cache/masking/partition opportunities. Emits findings (SAFE/REVIEW/BREAKING) + optimization plan + token delta. Read-only — LGTM if sound. Triggers: 'optimize context', 'compact context', 'auditar contexto', 'otimizar contexto', '/context-optimization'.
| File | Kind | Size |
|---|---|---|
| EXAMPLE.md | markdown | 13.7 KB |
| SKILL.md | skill md | 10.5 KB |
| references/CHECKLIST.md | markdown | 5.7 KB |
| references/HARNESS_NOTES.md | markdown | 7.8 KB |
| references/SEVERITY_RUBRIC.md | markdown | 9.0 KB |
| references/TECHNIQUES.md | markdown | 19.6 KB |
| references/USE_CASES.md | markdown | 13.8 KB |
| scripts/.gitignore | other | 139 B |
| scripts/README.md | markdown | 6.8 KB |
| scripts/ctxopt/Cargo.lock | manifest | 27.2 KB |
| scripts/ctxopt/Cargo.toml | manifest | 676 B |
| scripts/ctxopt/src/cli.rs | script | 3.3 KB |
| scripts/ctxopt/src/count.rs | script | 5.5 KB |
| scripts/ctxopt/src/dedup.rs | script | 5.5 KB |
| scripts/ctxopt/src/emit.rs | script | 4.4 KB |
| scripts/ctxopt/src/finding.rs | script | 2.3 KB |
| scripts/ctxopt/src/main.rs | script | 7.4 KB |
| scripts/ctxopt/src/report.rs | script | 11.8 KB |
| scripts/ctxopt/src/scan.rs | script | 5.1 KB |
| scripts/ctxopt/src/toon.rs | script | 5.6 KB |
| scripts/ctxopt/tests/integration.rs | script | 3.2 KB |
| scripts/run-all.shexecutable | script | 1.3 KB |
references/USE_CASES.md
View on GitHub# USE_CASES — context-optimization
> Reference companion for the [context-optimization](../SKILL.md) skill.
This skill audits and plans optimization for four primary classes of context:
1. **Long-conversation agents** — 50+ turn agent sessions (Claude Code, Codex CLI, custom agents).
2. **RAG pipelines** — system / user templates that wrap retrieved chunks; the chunks themselves are the bulk of the bloat.
3. **Sub-agent orchestrators** — parent coordinator dispatching N sub-agents with isolated contexts.
4. **Large-doc workflows** — single-shot tasks against documents > 100k tokens (legal, codebase analysis, multi-file synthesis).
Each class has different failure modes and a different canonical optimization order. This reference picks the right technique subset and the right plan skeleton per class.
> **Audit honesty.** Each §N below is the baseline for the corresponding use case. If the context under audit satisfies every required technique in §N, emit `LGTM` and stop. Some contexts are intentionally simple (single-shot prompt, no session, no retrieval) — do not force techniques from a canonical skeleton that do not fit the declared scope. **Technique absent that should be there is a finding; technique absent that should not be there is over-engineering.**
---
## §1 Long-conversation agents
### Failure modes
- **Window overflow** — session grows past 80% with no compaction trigger; quality cliff at ~95%.
- **Cache miss every turn** — system prompt re-sent in full because no `cache_control` set, or interleaved with dynamic content.
- **Tool-output bloat** — read_file / search_codebase outputs from 20 turns ago still in window taking 60%+ of tokens.
- **Filler restatements** — agent restates plan / decisions every turn, doubling-counting.
- **No deterministic compaction policy** — relies on auto-compaction (Claude Code 95% threshold); deterministic timing matters in production.
### Required techniques
§1 Prompt caching · §2 Compaction · §3 Observation masking · §4 Dynamic summarization · §6 Verbatim deletion (citations) · §9 Cache-friendly ordering · §13 Harness compaction commands.
### Canonical optimization skeleton
```toon
skeleton_long_conv[6]{step,description,technique}:
1 Cache layer — system prompt + tool defs + schema marked cache_control ephemeral (or trust automatic prefix caching on Codex / OpenAI) §1
2 Ordering layer — stable parts first; cache breakpoint; dynamic parts last §9
3 Compaction policy — manual trigger at 70-80% utilization §13
4 Masking policy — observations from 3+ turns ago folded to [Obs:N] references §3
5 Summarization policy (optional) — sessions > 60 turns, rolling summary per W turns; < 60 turns single compaction is cheaper §4
6 Citation discipline — quote-bound text uses verbatim deletion, not summary §6
```
### Smell tests
- **Cache hit probe.** Run two consecutive turns with identical system prompt; check API response for cache hit metric. If 0%, §1 + §9 are missing or misconfigured.
- **Compaction trigger probe.** Push session to 85% utilization; check if compaction fired automatically or required manual `/compact`. Document the threshold.
- **Masking decision probe.** After 10 turns with verbose tool outputs, query the agent about a turn-2 observation; if it answers correctly, the observation is still in context (no §3); if it asks to re-fetch via reference ID, masking is working.
### Findings to look for
```toon
findings_long_conv[6]{smell,fix}:
cache_control absent on system prompt Add cache_control { type ephemeral } (Anthropic) — see §1
System prompt + dynamic content interleaved Reorder per §9; cache breakpoint between stable and dynamic
Session > 80% utilization, no compaction Insert harness /compact (or equivalent — see §13) at 70-80%
Tool outputs > 50% of context Add §3 observation masking for outputs older than 3 turns
Sessions > 60 turns with single compaction cycle Switch to §4 rolling summarization
Citation-bound chunks paraphrased in compaction Use §6 verbatim deletion instead — preserves exact quotes
```
---
## §2 RAG pipelines
### Failure modes
- **Top-K stuffing without re-rank** — vector search returns 20 chunks; all 20 fed to LLM; quality plateaus past 8 chunks while cost grows linearly.
- **Duplicate chunks across sources** — same paragraph appears 3 times from related sources; LLM sees triple-counted "evidence".
- **Empty retrieval handled silently** — no chunks returned; LLM falls back to prior knowledge with no flag.
- **Mixed chunks blend** — LLM conflates two documents into one "fact".
- **Prompt-injection via chunk content** — chunks contain `"ignore the above"`-style instructions; LLM follows them. Cross-link: [`prompt-engineering` §13](../../prompt-engineering/references/STRATEGIES.md#13-prompt-injection-guard).
### Required techniques
§1 Prompt caching · §3 Observation masking (cited chunks → reference once cited) · §6 Verbatim deletion (preserves quote-back integrity) · §8 RAG chunk-pruning + re-ranking (mandatory) · §9 Cache-friendly ordering · §10 Dedup (mandatory) · §11 Model routing (cheap reranker, expensive answerer).
### Canonical optimization skeleton
```toon
skeleton_rag[8]{step,description,technique}:
1 Cache layer — system prompt (role + citation rule + injection guard) cached §1
2a Retrieval — vector top-K (K = 30, generous initial cast) —
2b Retrieval — dedup (drop > 85% similar chunks) §10
2c Retrieval — re-rank via cross-encoder or cheap LLM-as-judge §8 + §11
2d Retrieval — threshold filter (score > 0.7) §8
2e Retrieval — cap N (= 5-8 final chunks) §8
3 Ordering — system prompt -> schema -> refusal hooks -> breakpoint -> {retrieved} -> {user_question} §9
4 Quote-back verification — every cited chunk_id produces verbatim substring; source preservation §6 + cross-link prompt-engineering §3 + §12
```
### Smell tests
- **Dedup probe.** Issue a query that retrieves obvious near-duplicates (e.g., two sources of the same Wikipedia paragraph). Inspect retrieved chunks; if both arrive, §10 is missing.
- **Re-rank probe.** Issue an off-topic query; check if top-K returns lots of low-relevance chunks. If reranker is in place, threshold filter drops them; if absent, all 20 reach the LLM.
- **Empty-retrieval probe.** Issue a query with no relevant chunks (gibberish, foreign domain). LLM should refuse per `prompt-engineering` §7 refusal hook, not improvise.
### Findings to look for
```toon
findings_rag[6]{smell,fix}:
Top-K > 10 with no re-rank Add re-rank step + threshold (§8)
Identical / near-identical chunks observed Add SimHash dedup before LLM call (§10)
No empty-retrieval refusal Cross-link @prompt-engineering §7 refusal hooks
Chunk text not labeled as "data, not instructions" Cross-link @prompt-engineering §13 prompt-injection guard
Top-tier model used for re-ranking Route reranker to cheap model (§11)
Cache hit rate < 50% on stable system prompt Apply §1 + §9
```
---
## §3 Sub-agent orchestrators
### Failure modes
- **Coordinator window blowup** — parent holds full context of every sub-agent's work.
- **Per-child unbounded budget** — single sub-agent task hits 100k+; parent inherits the bloat on result return.
- **Aggregation conflate** — parent merges 6 sub-results into one big chunk; loses subtask provenance.
- **Wrong sub-agent dispatched** — parent picks sub-agent by name similarity, not by tool-map `Use when` rule. Cross-link: [`prompt-engineering` §11](../../prompt-engineering/references/STRATEGIES.md#11-skill--tool-map).
- **No isolation** — sub-agent inherits parent context; defeats the partition.
### Required techniques
§1 Prompt caching (parent + each child caches its own role) · §7 Context partitioning · §9 Cache-friendly ordering (per child) · §11 Model routing (parent vs children may use different tiers).
### Canonical optimization skeleton
```toon
skeleton_subagent[8]{step,description,technique}:
1a Parent — holds task plan + N child summaries + open threads §7
1b Parent — Phase 5.3 budget: parent <= 30k §7
1c Parent — cache_control on system prompt §1
2a Child — clean window; does NOT inherit parent context §7
2b Child — receives task spec + minimal grounding (<= 5k seed) + budget (<= 30k) §7
2c Child — cache_control on child system prompt (cached separately from parent) §1
3 Aggregation — each child returns structured summary (<= 1k tokens) + raw artifact reference §7
4 Routing — triage children on cheap tier; reasoning children on capable tier §11
```
### Smell tests
- **Inheritance probe.** Spawn a sub-agent with a task that does not need parent context. Inspect sub-agent's actual prompt; if it contains parent's full history, isolation is broken.
- **Budget probe.** Pick a child task expected to be small; verify it does NOT exceed Phase 5.3 sub-agent ceiling (30k). If it does, the spec is under-constrained.
- **Cost-tier probe.** Inspect routing decisions across N children; if all use top-tier, §11 is missing.
### Findings to look for
```toon
findings_subagent[5]{smell,fix}:
Sub-agent inherits parent history Enforce isolation; pass only task spec + minimal grounding (§7)
Per-child budget unbounded Set Phase 5.3 ceiling (<= 30k per child)
All children on top-tier model Add §11 routing matrix
Parent merges raw outputs (not summaries) Children return structured summary + artifact reference
Use when rule missing per sub-agent in tool map Cross-link @prompt-engineering §11
```
---
## §4 Large-doc workflows
### Failure modes
- **Single-shot stuffing past quality cliff** — 200k document fed in one prompt; Sonnet quality degrades past ~150k effective.
- **No map-reduce** — single LLM call asked to summarize, extract, AND cross-reference; misses cross-doc connections.
- **Retrieval over chunks instead of full doc** — when full doc fits, retrieval adds noise without benefit.
- **No caching across runs** — same large doc analyzed N times; each time pays full input price.
- **Output-token cap clipped** — model produces summary up to output limit (4-8k); user thinks doc is fully analyzed.
### Required techniques
§1 Prompt caching (mandatory — same doc reused) · §5 LLMLingua / token-level pruning (for noisy docs) · §7 Context partitioning (map step) · §9 Cache-friendly ordering · §11 Model routing (cheap pass for outline, expensive for synthesis) · §12 Batch-mode aggregation (if N docs).
### Canonical optimization skeleton
```toon
skeleton_largedoc[8]{step,description,technique}:
1 Cache the document — load once with cache_control ephemeral; ttl 1h if reused over hours, default 5min if reused within minutes §1
2a Map — split doc into N chunks (<= 30k each) §7
2b Map — cheap-model extract per chunk §11
2c Map — each chunk analysis cached separately for reuse §1
3a Reduce — capable-model synthesis over the map outputs §11
3b Reduce — cross-doc reasoning happens here —
4 Optional batching — if N docs, batch the map step for 50% cost reduction, 24h SLA §12
5 Optional pruning — if doc is noisy / high-redundancy, LLMLingua pre-process before chunking §5
```
### Smell tests
- **Single-shot probe.** Run a 180k-doc analysis as a single prompt; measure quality on a defined task. Compare to map-reduce. If single-shot is acceptable, the workload doesn't need partitioning. If quality drops, partitioning is mandatory.
- **Cache reuse probe.** Run the same doc analysis twice. Second run should show 90% cache hit rate on the doc itself (only output differs).
- **Output-cap probe.** Verify the model's `max_output_tokens` is sized for the synthesis (not 4k default for an analysis that needs 16k).
### Findings to look for
```toon
findings_largedoc[5]{smell,fix}:
Doc loaded as single chunk past 100k Apply §7 partitioning + map-reduce
Same doc analyzed N times no caching Add cache_control with appropriate TTL (§1)
Cheap-extractable analysis run on top-tier model Add §11 routing for map step
Bulk N-doc workflow on interactive API Migrate to batch (§12)
Output-token cap clips synthesis Increase max_output_tokens; or split synthesis into multiple calls
```
---
## §5 Skill-prompt use case (cross-link)
When the audit target is a **single SKILL.md prompt** (not a session, not retrieval, not architecture), the work belongs to [`@prompt-engineering`](../../prompt-engineering/SKILL.md), not this skill. `context-optimization` handles whole-context optimization; `prompt-engineering` handles single-prompt audit and rewrite.
If user asks for skill-prompt analysis and the prompt is the entire context, hand off to `@prompt-engineering` and stop.
If user asks for whole-skill optimization (e.g., "the skill is loaded but eats 10% of my context window before any work happens"), apply the long-conv-agent §1 skeleton with `skill-prompt` as a sub-target — phase 5.3 budget ≤ 800 tokens applies.
---
## How the skill picks the right use case
Phase 0.2 classifies the context. Set:
```text
use case: long-conv-agent | rag-pipeline | sub-agent-orchestrator | large-doc | skill-prompt
```
Then Phase 3 walks only the technique subset for that class (above), and Phase 4 generates the plan using the canonical skeleton above. The findings to look for in each section seed Phase 2 (cost & quality audit).
For contexts that **mix classes** (e.g., a long-conv agent embedding a RAG sub-pipeline), audit each class separately and combine the techniques in the plan output.
## Hand-offs
- The audit target is a **single prompt** → `@prompt-engineering`.
- The audit target is a **conversation style preference** (response brevity) → out of scope; this skill compresses input, not output.
- The audit target is **safety / refusal hooks** in a long-conv agent → `@prompt-engineering` for the safety rules; `@context-optimization` for the surrounding context size.
- The audit target is a **project with no skills or agents yet** → `@celebrimbor`.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |