Context optimization

Context Optimization Lifecycle

Audits and plans optimization for an LLM context (system prompt, tool defs, message history, retrieved chunks, tool outputs). Two modes, classified at Phase 0.2: Audit (Phase 0..6 lifecycle → 5-block report) when a session/context is pasted; Guide (catalog lookup §1..§13) when invoked as a knowledge source. Read-only — never auto-applies. Evidence-first: every finding cites a measurable category in the inventory or a configuration line. Zero-findings is a valid LGTM.

When to Use

• Long-conversation agents (50+ turn sessions; cache miss + tool-output bloat + late compaction).
• RAG pipelines (top-K stuffing without re-rank, duplicate chunks, prompt-injection via chunk content).
• Sub-agent orchestrators (parent window blowup, per-child unbounded budgets, cost-tier mis-routing).
• Large-doc workflows (single-shot > 100k, no caching across runs, output-token cap clipping synthesis).
• Skill-prompt context (whole-skill payload eats budget on every load).

Trigger: user pastes session/RAG template, statusline shows ≥ 80% utilization, or another skill cross-links @context-optimization.

Do not use when

• Audit target is a single prompt (clarity, refusal hooks, schema) — use @prompt-engineering.
• User wants response brevity — use @caveman.
• User wants new skill scaffold — use @skill-creator.
• Phase 0.5 triage gate fires (trivial context).
• Domain has stricter compliance than the skill can verify (legal hold, audit trail).

Prerequisites

Input	Required	How to obtain
Context inventory (categories + sizes)	Yes	User pastes, or bash scripts/run-all.sh <project> (invokes ctxopt Rust binary)
Use case	Yes	long-conv-agent / rag-pipeline / sub-agent-orchestrator / large-doc / skill-prompt
Target harness	No	claude-code / codex / opencode / antigravity / agnostic — drives §13 plan output
Current utilization (%)	No	Estimate via ctxopt count <project> or harness statusline
Known degradation signal	No	Quality drop, cost spike, latency — focuses the audit

Skill never sends context to another model. Findings derived from inventory against TECHNIQUES.md catalog.

Phase 0 — Capture & Classify

Capture inventory verbatim (Phase 0.1). Classify mode + use case + harness on three axes (Phase 0.2). Bound against use-case ceiling (Phase 0.3). Honest audit pledge — see CHECKLIST §Skill self-audit (Phase 0.4). Then triage gate:

0.5 Triage gate

Drop the audit when all three hold:

• Estimated context < 8000 tokens
• Window utilization < 50%
• No degradation signal reported

→ emit Block 1 (inventory) + Block 2 row (out of scope: trivial context — audit overhead exceeds value) + stop.

Otherwise, proceed to Phase 1.

Phase 1 — Inventory

Break inventory into five categories (system prompt · tool defs · message history · retrieved chunks · tool outputs) with token estimate per category. Top category > 50% = top-of-mind finding. Evidence-based audit invokes the ctxopt Rust binary (built at install time):

bash scripts/run-all.sh <project_root>
# or directly:
scripts/bin/ctxopt run-all <project_root> --format toon

Outputs out/findings.toon, out/summary.{toon,json}, out/report.md. Detailed checklist: CHECKLIST Phase 1.

Phase 2 — Cost & Quality Audit

Walk cost levers (cache hit rate · dedup ratio · masking opportunity · partition candidates · harness primitive coverage) against the inventory. Each lever absent or weakly applied is a finding with category-cite. Severity per SEVERITY_RUBRIC.md. Heuristic findings start Medium; promotion requires manual confirmation.

Phase 3 — Technique Selection

Walk TECHNIQUES.md §1..§13. Use case dispatches the subset (see TECHNIQUES §How the skill uses):

Use case	Required techniques
long-conv-agent	§1, §2, §3, §4, §6, §9, §13
rag-pipeline	§1, §3, §6, §8, §9, §10, §11
sub-agent-orchestrator	§1, §7, §9, §11
large-doc	§1, §5, §7, §9, §11, §12
skill-prompt	cross-link @prompt-engineering for single-prompt audit

Common context-bloat smells (quick-detection): see TECHNIQUES §Common context-bloat smells.

Phase 4 — Plan Recommendations

Plan ordered by ROI (highest token-cost or quality-impact first). Canonical skeleton per use case in USE_CASES.md §1–§4. Generic order: cache layer (§1+§9) → compression (§2/§3/§4/§5/§6) → architecture (§7) → RAG-specific (§8/§10) → cost (§11/§12) → harness (§13).

4.1 Harness-specific plan output

When harness ≠ agnostic, Block 3 emits concrete commands per HARNESS_NOTES.md: Claude Code /compact, Codex session.compaction, Antigravity manual UI re-prompt. A plan that says "use compaction" without naming the harness primitive is itself a finding.

4.2 Living-context versioning

If the audited configuration has a version field, Block 3 emits a SemVer hint: PATCH (only SAFE), MINOR (≥ 1 REVIEW), MAJOR (≥ 1 BREAKING). Soft-spec; skips when no version.

Phase 5 — Token Economy

5.1 Compression rules

Never compact a never/must not/do not rule. Never drop a refusal hook during compaction. Never paraphrase citation-bound text (use §6 verbatim deletion). Always dedupe (§10) before compacting (§2). Always preserve verbatim when surviving content is citation-bound. Detailed checklist: CHECKLIST Phase 5.

5.2 Reporting the delta

Estimate before/after token count. Report signed delta + cache hit projection + invariants preserved (safety rules, refusal hooks, citation chunk_ids).

5.3 Token budget per use case

The plan respects a per-use-case ceiling. Excess → finding T-001 Token budget exceeded (REVIEW).

Use case	Ceiling (after plan applied)
long-conv-agent	≤ 100k tokens (50% Sonnet/Opus 200k window)
rag-pipeline	stable prefix ≤ 8k + dynamic ≤ 32k
sub-agent-orchestrator	parent ≤ 30k; each child ≤ 30k
large-doc	≤ 200k (single-shot, no growth)
skill-prompt	≤ 800 tokens (aligns with prompt-engineering 5.3)
Other	≤ 50% of model window

User can override with explicit rationale; without override, T-001 fires.

5.4 Cache-friendly ordering

Position stable (system prompt, tool defs, schema, refusal hooks, few-shot) before dynamic (user input, retrieved chunks, conversation history). Anthropic prompt caching reuses prefix tokens with 5min/1h TTL; OpenAI auto-caches prefixes ≥ 1024 tokens. Reordering converts repeated tokens into cache hits — without §9, §1 caches only the leading stable prefix until the first dynamic byte.

Phase 6 — Output

Five-block report. Block 5 conditional (REQUIRED if overall risk = REVIEW or BREAKING; OPTIONAL if SAFE).

Block	Content
1	Original context inventory (verbatim, fenced)
2	Findings table + per-finding detail (id, severity, confidence, risk, category-cite, fix, technique §N)
3	Optimization plan (ordered by ROI; harness-specific commands per HARNESS_NOTES.md when harness ≠ agnostic)
4	Summary table (cost lever coverage / token delta / cache-hit projection / risk tag / confidence)
5	Verification suggestions

Worked example + verbatim output template: EXAMPLE.md. Zero-findings contract + LGTM rules: CHECKLIST §Skill self-audit.

Constraints

Three load-bearing rules (full 15-rule list in CHECKLIST §Skill self-audit):

Rule	Why
Never apply the plan automatically	Reviewer not optimizer — Block 3 = proposal
Never strip a safety rule from system prompt during compaction	never/must not/do not/refuse if survive every compaction
Always emit Block 1 verbatim	Inventory contract; second auditor must reach same verdict

Related Skills

• @prompt-engineering — primary sibling. Audits single prompts; this skill audits whole context. Run @prompt-engineering first to fix the prompt; then /valarmindskills:context-optimization to optimize the surrounding context.
• @caveman — compresses response (output). This skill compresses input (context).
• @skill-creator — scaffolds new skills.
• @code-security-review — pattern source for scripts/ architecture.

References

• TECHNIQUES — §1..§13 catalog (cache, compression, architecture, RAG, cost, tool-specific)
• USE_CASES — canonical skeletons + findings catalogs for the four primary classes
• CHECKLIST — copy-paste cheat sheet by phase + skill self-audit
• SEVERITY_RUBRIC — Severity × Category matrix and risk-tag rubric
• HARNESS_NOTES — Claude Code / Codex / OpenCode / Antigravity primitives
• EXAMPLE — long-conv-agent worked example with verbatim output template
• scripts/ — evidence-based audit tools (scripts/README.md)