Skip to content

Bruno-Cunha-Souza/ValarMindSkills / skills/context-optimization

context-optimization

Unverified

Lifecycle 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'.

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 — out of scope; this skill compresses input (context), not output.
  • User wants project-specific skills or agents generated — use @celebrimbor.
  • Phase 0.5 triage gate fires (trivial context).
  • Domain has stricter compliance than the skill can verify (legal hold, audit trail).

Prerequisites

InputRequiredHow to obtain
Context inventory (categories + sizes)YesUser pastes, or bash scripts/run-all.sh <project> (invokes ctxopt Rust binary)
Use caseYeslong-conv-agent / rag-pipeline / sub-agent-orchestrator / large-doc / skill-prompt
Target harnessNoclaude-code / codex / opencode / antigravity / agnostic — drives §13 plan output
Current utilization (%)NoEstimate via ctxopt count <project> or harness statusline
Known degradation signalNoQuality 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 caseRequired 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-promptcross-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 caseCeiling (after plan applied)
long-conv-agent≤ 100k tokens (50% Sonnet/Opus 200k window)
rag-pipelinestable prefix ≤ 8k + dynamic ≤ 32k
sub-agent-orchestratorparent ≤ 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).

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

RuleWhy
Never apply the plan automaticallyReviewer not optimizer — Block 3 = proposal
Never strip a safety rule from system prompt during compactionnever/must not/do not/refuse if survive every compaction
Always emit Block 1 verbatimInventory 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.
  • @celebrimbor — forges project-specific skills, agents, and tool scripts.
  • @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)
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: 470kUpdated Claude CodeCodexVerifiedInstall
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: 470kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 470kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall