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 |
EXAMPLE.md
View on GitHub# EXAMPLE — context-optimization
> Worked example end-to-end of [context-optimization](SKILL.md). Long-conversation agent at 94% utilization → audited, optimization plan generated, Block 5 verification probes proposed.
## Input
User reports their Claude Code session has degraded after 80 turns of work on a Go REST API codebase. The statusline shows `94%` and the agent is starting to confuse paths from earlier turns. User runs:
```bash
bash scripts/run-all.sh ~/.claude/projects/abc123/
# under the hood: scripts/bin/ctxopt run-all <path> --format toon
```
The Rust binary `ctxopt` emits `out/findings.toon` (TOON format — 30-60% fewer tokens than JSONL when read by an LLM), `out/summary.{toon,json}`, and `out/report.md`. User pastes the inventory + first findings to the skill:
```text
session: dev-api-refactor
turns: 80
size: 187,432 tokens (94% of 200k Sonnet 4.6 window)
harness: claude-code
```
## Phase 0 — Capture & Classify
```text
ORIGINAL CONTEXT INVENTORY (verbatim categories + sizes):
"""
system prompt: 1,240 tokens (0.7%)
tool definitions: 8,420 tokens (4.5%)
message history: 92,150 tokens (49.2%) — 80 turns
retrieved chunks: 0 tokens (0%)
tool outputs: 85,622 tokens (45.7%)
TOTAL: 187,432 tokens / 200,000 = 94% utilization
"""
mode: audit
use case: long-conv-agent
harness: claude-code
triage gate (Phase 0.5): NOT triggered
- size 187k > 8k threshold
- utilization 94% > 50%
- degradation reported ("agent confusing paths from earlier turns")
→ proceed to Phase 1
```
Honest audit pledge: cite verbatim from inventory · read long-conv-agent baseline first · run scripts before claiming missing technique.
## Phase 1 — Inventory
Top categories: **message history (49.2%)** + **tool outputs (45.7%)** = 94.9% of total. System prompt + tool definitions = 5.2% (small but uncached — payback large per call).
## Phase 2 — Cost & Quality Audit
| Lever | Detection | Severity |
| --- | --- | --- |
| Cache hit rate | `cache_control` ABSENT on system prompt + tool defs | High (uncached on every turn — 0% cache hit projected) |
| Compaction trigger | NO manual trigger documented; relies on auto-compaction at 95% | Critical (currently at 94% — overdue) |
| Masking opportunity | Tool outputs ~85k = 45.7% of context, ages span 80 turns | High (no §3 applied) |
| Partition candidates | Single-context workflow; subtasks could split (search vs analyze vs apply) | Low for this use case (long-conv-agent skeleton, not sub-agent-orchestrator) |
| §9 ordering | Stable / dynamic interleaved? Yes — system prompt has dynamic timestamp | Medium |
| §13 harness primitive | Plan must cite `/compact` (Claude Code) | (will be cited in Block 3) |
## Phase 3 — Technique Selection
Use case = `long-conv-agent`. Required techniques per [TECHNIQUES §How the skill uses](references/TECHNIQUES.md#how-the-skill-uses-this-catalog): §1, §2, §3, §4, §6, §9, §13. Walk each:
- **§1 Prompt caching** — ABSENT. Critical for multi-turn; 80 turns × full prefix = enormous waste.
- **§2 Compaction** — NO manual trigger. Auto at 95% is too late + opaque.
- **§3 Observation masking** — ABSENT. 80 turns × verbose tool outputs = 45.7% of context.
- **§4 Dynamic summarization** — Optional (session not yet > 60 turns of growth — borderline). Defer.
- **§6 Verbatim deletion** — N/A (no citation-bound chunks in this session; pure code-edit).
- **§9 Cache-friendly ordering** — Mixed; current prompt has dynamic timestamp early.
- **§13 Harness command** — Will cite `/compact` in plan (REQUIRED per Phase 4.1).
## Findings (detail blocks)
```text
C-001 — No compaction trigger above 80% utilization
Phase: 2 Severity: Critical Confidence: High Risk: REVIEW
Category: message history (92k) + tool outputs (85k) = 94% util
Issue: Auto-compaction (Claude Code 95% threshold) is implementation-dependent
and opaque (user can't see what was elided). Production sessions need
deterministic timing.
Fix: Trigger /compact at 75% utilization (manual). See HARNESS_NOTES Claude Code.
Technique: [§2](references/TECHNIQUES.md#2-compaction-anthropic-auto--manual)
+ [§13](references/TECHNIQUES.md#13-harness-compaction-commands-compact-sessioncompaction)
C-002 — cache_control absent on system prompt + tool defs
Phase: 2 Severity: High Confidence: High Risk: SAFE
Category: system prompt (1.2k) + tool defs (8.4k) = 9.7k stable prefix
Issue: Without cache_control, Anthropic re-processes 9.7k tokens at full input
price every turn. Over 80 turns, that's 776k cumulative re-processed
tokens. Cache write 1.25× × 1 + cache read 0.1× × 79 = 9.15× equivalent
input cost; without cache, 80× full price = 8.7× more expensive.
Fix: Add cache_control: { type: "ephemeral" } on system prompt block + tool defs block.
Technique: [§1](references/TECHNIQUES.md#1-prompt-caching-5min--1h-ttl-stable-prefix-exact-match)
C-003 — Tool outputs > 45% of context, no masking
Phase: 3 §3 Severity: High Confidence: Medium Risk: REVIEW
Category: tool outputs 85,622 tokens (45.7%)
Issue: Verbose read_file / search_codebase outputs from turns 1..50 still in
context. 80% of these have already been used to make decisions — the
raw output is no longer load-bearing.
Fix: Replace tool outputs from turns > 3 ago with [Obs:OBS-NNN] references
+ 1-line key conclusion. Restore on demand if agent re-fetches.
Technique: [§3](references/TECHNIQUES.md#3-observation-masking)
C-004 — Stable / dynamic content interleaved (§9 violation)
Phase: 3 §9 Severity: Medium Confidence: High Risk: SAFE
Category: system prompt (1.2k)
Issue: System prompt block contains "Today is {date}" mid-block. Even with §1
cache_control added, prefix cache invalidates at first dynamic byte —
only role grounding before the date is cached.
Fix: Move {date} into user message or below cache breakpoint. Stable parts
(role, tools, schema) come first; dynamic parts (date, query, history)
come after the breakpoint.
Technique: [§9](references/TECHNIQUES.md#9-cache-friendly-ordering-stable--dynamic)
C-005 — No deterministic compaction policy documented
Phase: 4 §13 Severity: Medium Confidence: High Risk: SAFE
Category: workflow / runbook
Issue: Plan output should cite the harness primitive (Claude Code: /compact)
so the user can act without harness lookup.
Fix: Plan Block 3 must emit "/compact at 75% utilization" verbatim.
Technique: [§13](references/TECHNIQUES.md#13-harness-compaction-commands-compact-sessioncompaction)
+ [HARNESS_NOTES Claude Code](references/HARNESS_NOTES.md#claude-code)
```
## Phase 5 — Token Economy
Plan-projected delta:
```text
Token delta:
before: 187,432 tokens (94% of 200k window)
after: 54,800 tokens (28% of 200k window)
delta: −132,632 tokens (−70.8%)
cache hit projection: 0% → 67% on stable prefix (9.7k tokens cached)
invariants preserved:
- system prompt content (cache_control wraps, doesn't change content)
- all `never`/`must not` rules
- last 5 turns verbatim (compaction summarizes turns 1..75 only)
- all decisions / commitments / open threads (compaction summary preserves these)
```
Use-case `long-conv-agent` budget per [Phase 5.3](SKILL.md#53-token-budget-per-use-case): ≤ 100k tokens. Projected after = 54,800 → within budget. T-001 not triggered.
## Phase 6 — Output
### Block 1 — Original context inventory (verbatim)
```text
| Category | Tokens | % of total |
| ----------------- | ---------- | ---------- |
| system prompt | 1,240 | 0.7% |
| tool definitions | 8,420 | 4.5% |
| message history | 92,150 | 49.2% |
| retrieved chunks | 0 | 0% |
| tool outputs | 85,622 | 45.7% |
| **TOTAL** | 187,432 | 94% of 200k window |
```
### Block 2 — Findings (summary table)
| ID | Sev | Conf | Risk | Phase | Title |
| ----- | -------- | ------ | -------- | ----- | ---------------------------------------- |
| C-001 | Critical | High | REVIEW | 2 | No compaction trigger above 80% util |
| C-002 | High | High | SAFE | 2 | cache_control absent on system prompt |
| C-003 | High | Medium | REVIEW | 3 | Tool outputs > 45%, no §3 masking |
| C-004 | Medium | High | SAFE | 3 | Stable / dynamic interleaved (§9) |
| C-005 | Medium | High | SAFE | 4 | No harness primitive in plan |
### Block 3 — Optimization plan
```text
Order: cache layer → compression → architecture → RAG → cost → harness.
(architecture / RAG / cost N/A for this single-agent code-edit session.)
1. (SAFE — C-002) Add cache_control: { type: "ephemeral" } on:
- system prompt block (1.2k tokens)
- tool definitions block (8.4k tokens)
Cache breakpoint AFTER tool defs, BEFORE conversation history.
Expected: 67% cache hit projection on next 79 turns.
2. (SAFE — C-004) Move dynamic content (current date, current branch) OUT of
system prompt. Place at top of user message or below cache breakpoint.
3. (REVIEW — C-001, C-005) Trigger /compact at 75% utilization manually.
Currently at 94% — overdue. Run: /compact
Compaction summary preserves: decisions, commitments, open threads, all
`never`/`must not` rules, last 5 turns verbatim.
4. (REVIEW — C-003) Apply observation masking on tool outputs > 3 turns old.
Pattern: replace raw output with `[Obs:OBS-NNN elided. Key: <one-line>]`.
Re-fetch via read_file / search_codebase if needed in later turns.
Harness: claude-code
- /compact at 75% utilization (Claude Code statusline indicator).
- cache_control marked via MCP server config (if applicable).
- Watch ~/.claude/projects/<hash>/<session>.jsonl for post-compaction state.
```
### Block 4 — Summary
| Metric | Before | After |
| ---------------------------- | ------------- | -------------- |
| context size | 187,432 tk | 54,800 tk |
| utilization | 94% | 28% |
| cost lever coverage (long-conv-agent) | 0 / 7 | 6 / 7 |
| cache hit projection | 0% | 67% |
| risk tag (overall) | — | REVIEW |
| confidence | — | High |
Suggested next step:
1. Adopt Block 3 plan in order — cache layer first (SAFE, lowest risk + highest payback).
2. Run Block 5 verification suggestions.
3. Re-run /valarmindskills:context-optimization after one production cycle (next 20-50 turns).
### Block 5 — Verification suggestions
(Required: overall Risk = REVIEW.)
- **Cache hit probe.** After applying step 1 (cache_control), make 3 consecutive
turns and inspect API response cache metric. Expect ≥ 50% on turn 2 onwards.
- **Compaction probe.** After /compact (step 3), inspect `~/.claude/projects/<hash>/<session>.jsonl`
— confirm summary preserves all `never`/`must not` rules from system prompt
(grep for them). Expect ALL preserved.
- **Masking probe.** After applying step 4, query the agent about a turn-2
observation. Expect: agent refers to `[Obs:OBS-NNN]` and offers re-fetch, not
verbose recall. If verbose recall, masking didn't apply.
- **Re-audit probe.** Re-run `bash scripts/run-all.sh ~/.claude/projects/<hash>/`.
Expect: 0 Critical, 0 High findings (C-001, C-002, C-003 cleared); only Lows /
Info remain.
## What this demonstrates
- **Block 1 verbatim** — the inventory contract every later block is checked against. Categories + sizes preserved exactly as scripts emit.
- **5 findings split** between cost (C-001, C-002), quality (C-003, C-004), and process (C-005). Each cites a specific category from Block 1 (no speculation).
- **Severity calibrated** — only the compaction overdue is Critical (impact × likelihood: agent already degrading on every turn). cache_control absence is High (production multi-turn). No inflation.
- **Risk tags differentiate** SAFE additions (cache_control, ordering) from REVIEW changes (compaction summary, masking — some inputs handled differently in next turns).
- **Token delta strongly negative** — 94% → 28% = 70.8% reduction. Justified by inventory split (45% tool outputs maskable, 50% history compactable).
- **Block 5 mandatory here** because overall Risk = REVIEW. Probes are concrete (cache hit metric, jsonl grep, re-audit script).
- **Harness primitive cited** (per Phase 4.1) — `/compact` named verbatim, not `"use compaction"`.
## Other use cases
This worked example covers **`long-conv-agent`** use case. For the four primary classes:
- **`rag-pipeline`** — see [USE_CASES §2](references/USE_CASES.md#2-rag-pipelines) for failure modes (top-K stuffing, dedup absence, prompt-injection via chunk content) + canonical skeleton (vector → dedup → re-rank → threshold → cap N).
- **`sub-agent-orchestrator`** — see [USE_CASES §3](references/USE_CASES.md#3-sub-agent-orchestrators) for parent / child budgeting, isolation enforcement, routing matrix.
- **`large-doc`** — see [USE_CASES §4](references/USE_CASES.md#4-large-doc-workflows) for map-reduce + caching across runs.
- **`skill-prompt`** — cross-link to `@prompt-engineering` for single-prompt audit; this skill handles whole-skill context if it exceeds budget.
Producing 4× expanded EXAMPLE would duplicate USE_CASES.md material; the canonical skeletons there are the worked examples for those classes.
## Fonte
Repository canonical: [`skills/context-optimization/EXAMPLE.md`](file:///Users/brunosouza/Dev/Bruno-Cunha-Souza/ValarMind/ValarMindSkills/skills/context-optimization/EXAMPLE.md)
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 |