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/SEVERITY_RUBRIC.md
View on GitHub# SEVERITY_RUBRIC — context-optimization
> Reference companion for the [context-optimization](../SKILL.md) skill.
Severity calibrates how blocking a finding is. Risk tag calibrates how invasive the proposed fix is. Confidence calibrates how willing the reviewer is to stand behind the finding. Findings missing any of the three are dropped.
## Severity by category
Each row is a category (Cost waste, Cache miss, Quality degradation, Token bloat, Architecture risk). Each column is a severity. A finding lands at the cell where its symptom matches.
```toon
severity_matrix[25]{severity,category,description}:
critical cost Production agent calling top-tier model on triage tasks ($/M scaling 10x+)
critical cache Cache breakpoint after dynamic content -> 0% cache hit on multi-turn
critical quality Compaction summarizing safety rules / refusal hooks; semantic loss on commitments
critical bloat Context > 95% capacity with no compaction triggered
critical architecture Sub-agent partition missing on 4+ subtask workflow producing rate-limit failures
high cost Bulk eval running interactive API ignoring batch mode
high cache Stable content interleaved with dynamic; partial cache hit only
high quality Verbatim deletion (§6) replaced with paraphrase summarization on citation-bound RAG
high bloat Tool outputs > 70% of context, no masking
high architecture Single-context monolith on workflow that should partition
medium cost Top-tier model used for structured extraction with no routing
medium cache System prompt not marked for caching at all
medium quality Re-rank threshold too aggressive -> relevant chunks dropped
medium bloat > 40% redundant chunks (no §10 dedup)
medium architecture Coordinator -> sub-agent budget unbounded (no Phase 5.3 cap)
low cost Cache TTL 1h chosen for prompts re-used every 5 minutes (write-cost premium with no payback)
low cache Suboptimal ordering of stable parts (e.g. schema after refusal hook)
low quality Summary loses non-load-bearing back-and-forth without flag
low bloat > 15% redundancy in retrieved chunks
low architecture Sub-agent boundaries not documented in plan
info cost Routing matrix could be tighter
info cache Could add second cache breakpoint for tool defs
info quality Could log compaction events for observability
info bloat Filler phrases in system prompt
info architecture Consider parallelism on independent sub-agents
```
A single context can have findings across multiple categories. Aggregate **at the highest single-finding severity**, not by counting.
### Use case-specific severity patterns
When use case = `long-conv-agent`, the dominant failure modes are compaction timing and cache misses. When use case = `rag-pipeline`, dedup + chunk-pruning + injection-guard dominate. Apply this table only for the noted use cases; for others, read the matrix above.
```toon
use_case_severity[6]{pattern,severity,use_case,reasoning}:
No compaction trigger documented above 80% capacity critical long-conv-agent Quality cliff at ~95%; auto-compaction is implementation-dependent
cache_control absent on system prompt high long-conv-agent 90% of cache savings forgone on every turn
Re-rank step missing on RAG with > 10 chunks high rag-pipeline Quality drops past 8 chunks without re-rank; cost grows linearly
Dedup absent on RAG with overlapping sources medium rag-pipeline 15-40% wasted tokens
Sub-agent budget per Phase 5.3 unbounded high sub-agent-orchestrator Single child can blow window; aggregation produces oversized parent context
Large doc loaded as single chunk with no map-reduce high large-doc Quality degrades past ~100k; partition / map-reduce mandatory
```
## Calibration aids — Impact × Likelihood
For findings whose category placement is borderline, score **impact** (what happens if the bloat / miss / drift continues) against **likelihood** (how often this gap will trigger in the context's actual use case):
```toon
impact_likelihood[9]{impact,likelihood,severity}:
low low low
low medium low
low high medium
medium low low
medium medium medium
medium high high
high low medium
high medium high
high high critical
```
A cache miss that triggers on every run with high impact (production multi-turn agent at scale, no §1 caching) is **Critical**. A token-economy gap with low impact and rare trigger is **Low**.
## Risk tag — by fix scope
Tag every fix so the user knows how invasive adoption is.
```toon
risk_tags[3]{tag,meaning,example}:
SAFE Reword, reordering, or pure addition that does not change observed behavior; same inputs still produce same outputs more cheaply / cached Add cache_control ephemeral; reorder stable-then-dynamic per §9; deduplicate overlapping retrieval chunks per §10
REVIEW Changes which inputs survive: compaction summarizes earlier turns, masking elides observations, re-rank drops chunks; some inputs handled differently Apply §2 compaction at 70% threshold; apply §3 masking after 3 turns; apply §8 re-rank dropping low-score chunks
BREAKING Restructures the architecture: partitioning across N sub-agents, switching to batch mode, changing output schema for routed model Switch from monolith to §7 sub-agent partitioning; route triage steps to smaller model (§11) with different tool format; move bulk path to §12 batch API
```
A plan usually contains multiple findings of mixed risk. Report the **overall risk tag** as the worst (most invasive) tag among adopted findings.
## Confidence — by evidence
```toon
confidence[3]{level,when,action}:
high Gap is mechanical (technique from TECHNIQUES.md provably absent — script-detected via ctxopt scan/count/dedup); use case demands it; fix is well-known Adopt without further review
medium Technique partially present (e.g. §1 caching enabled but ordering per §9 wrong) or use case ambiguous and gap may be intentional Adopt after one-line confirmation from user about intent
low Auditor would benefit from second opinion; harness unclear, workload undocumented, or technique on borderline Escalate. If Severity >= High and Confidence = Low, mark needs human review
```
## Calibration: heuristic findings start at Medium
Findings derived from absence-detection heuristics (`ctxopt scan`, `ctxopt count`, `ctxopt dedup`) begin at **Medium** unless the auditor can manually argue for promotion. Promotion to High or Critical requires:
1. The technique is mandatory for the declared use case (per the [TECHNIQUES.md mapping](TECHNIQUES.md#how-the-skill-uses-this-catalog)).
2. The reviewer has read the surrounding context and confirmed the gap is not satisfied by an equivalent construct (e.g., custom compaction loop instead of `/compact`).
Inflated severity erodes trust faster than missed findings.
## Anti-pattern: padding the report
Three failure modes erode audit credibility:
1. **Inventing Minors to fill space.** Zero-findings is a valid result. If the context passes for the declared use case, emit `LGTM` and stop.
2. **Promoting Minors to Major.** Severity is bound to impact × likelihood, not to report length.
3. **Hedging without evidence.** `"This could potentially be better"` without a concrete category-cite or quote is noise. Drop it.
**Reproducibility rule.** Every finding must be reproducible from the original context inventory (Block 1). If a second auditor reading **only** Block 1 cannot identify the same gap, the finding is speculation and must be dropped.
## Floor: when not to file a finding
Drop the finding entirely (do not file as Info either) if **any** of the following holds:
- The context is for a workload the technique table does not require for that use case.
- The technique is explicitly turned off in the context with a one-line rationale (e.g., `# Caching disabled: every prompt is dynamic by product requirement`).
- The context fits inside the Phase 0.5 triage gate.
## Decision tree (one-glance summary)
```text
Q1. Is the technique required for this use case?
no → drop the finding.
yes → continue.
Q2. Is the technique mechanically absent (regex / script / structure check)?
yes → start at Medium.
no → start at Low or Info.
Q3. What is the impact × likelihood?
high × every-run → promote to Critical.
high × frequent → promote to High.
other → keep at Medium / Low per the rubric above.
Q4. Risk tag for the fix?
pure reword / reorder / addition → SAFE
drops / summarizes / re-ranks → REVIEW
changes architecture / schema → BREAKING
Q5. Confidence?
mechanical absence + required technique → High
partial / ambiguous → Medium
auditor unsure of harness or workload → Low — escalate if Sev ≥ High
```
## Shared lineage with prompt-engineering
§9 cache-friendly ordering also appears in [`prompt-engineering` Phase 5.4](../../prompt-engineering/SKILL.md). The two skills view the same primitive from different angles: `prompt-engineering` audits a single prompt and recommends ordering; `context-optimization` audits the whole context and recommends placement. Findings can cite both lineages without redundancy.
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 |