# Context Engineering Review Skill

Most agent failures aren't model failures — they're context failures: instructions buried under retrieval dumps, stale history contradicting fresh facts, twelve tool definitions the task never needed. This skill audits the *assembled window*, not just the prompt text.

## What This Skill Produces

- A **context inventory**: every component in the window, its size, and who put it there
- A **keep / cut / restructure verdict** per component, with the reasoning
- **Ordering and cache-alignment fixes** (stable prefix first, volatile content last)
- A **token budget** per component with an enforcement point

## Required Inputs

Ask for (if not already provided):
- **A real assembled context** — an actual logged request (system prompt + messages + tools), not the template. If only the template exists, review that but flag that dynamic bloat is invisible
- **The failure or goal** — ignoring instructions? too expensive? inconsistent? slow?
- **What varies per request** (retrieval, history, user data) vs. what is static
- **The model and its context limit**, and current typical request size

## Review Method

**1. Inventory.** List every component in window order: system prompt sections, tool definitions, retrieved documents, conversation history, few-shot examples, injected state. For each: token count (estimate if unlogged), static vs. dynamic, and owner.

**2. Interrogate each component:**
- **Earning its tokens?** Would removing it change outputs on real traffic? The honest test is ablation, not intuition.
- **Right form?** Raw dumps (full HTML, whole files, unabridged history) almost always beat down to summaries, excerpts, or references the agent can expand via a tool.
- **Right position?** Instructions that must win go in the system prompt; volatile data goes late; nothing critical hides in the middle of a long window.
- **Fighting anything?** Contradictions between sections (persona says terse, examples are verbose; old history asserts what retrieval now refutes) are the classic "ignores instructions" root cause.

**3. Check the structural patterns:**
- **Cache alignment** — a byte-stable prefix (system prompt, tools) with per-request content after it; anything dynamic *inside* the prefix (timestamps, user names) breaks caching every request.
- **Tool sprawl** — tools the task can't need this turn dilute selection accuracy; load narrow toolsets per task or defer rarely-used schemas.
- **History policy** — unbounded transcripts are the top silent cost driver; define truncation/summarisation and what must survive it.
- **Retrieval discipline** — cap chunks by relevance score, not by k; label each chunk's source so the model can weigh it.

**4. Budget.** Assign each component a token ceiling that sums comfortably under the limit at p95, and name where it's enforced (the assembly code, not hope).

## Output Format

### Context Engineering Review: [feature/agent]

**Reviewed:** [a real request from date / the template]. **Current size:** [n] tokens typical, [n] p95, limit [n].

| # | Component | Tokens | Static? | Verdict | Fix |
|---|---|---|---|---|---|
| 1 | [system: persona] | | ✓ | Keep | — |
| 2 | [12 tool defs] | | ✓ | Restructure | [narrow per task] |
| 3 | [retrieval, k=20] | | dyn | Cut to k≤8 by score | |

**Conflicts found:** [each contradiction and which side should win]

**Ordering / caching:** [the reordered layout; what moves out of the stable prefix]

**Token budget:** [component → ceiling; enforcement point]. Projected size: [n] (−[x]%).

**Verify:** re-run [the eval suite / golden cases] after changes — cuts must be validated, not assumed safe (see `prompt-regression-suite`).

## Quality Checks

- [ ] The review used at least one real assembled request, or explicitly flags it could not
- [ ] Every verdict has a reason tied to the stated failure/goal, not generic advice
- [ ] Cache-breaking dynamic content in the stable prefix is called out with its cost
- [ ] The token budget sums under the model limit at p95 including output headroom
- [ ] Recommended cuts come with a validation step before they ship

## Anti-Patterns

- [ ] Do not review the prompt template and call it a context review — the bloat lives in the dynamic parts
- [ ] Do not recommend "shorten everything" — cutting the wrong 200 tokens costs more than keeping 2,000 idle ones
- [ ] Do not leave contradictions in place because each section "is fine alone" — the window is read as one document
- [ ] Do not treat more retrieval as more grounding — irrelevant chunks actively mislead
- [ ] Do not propose structure the assembly code can't enforce — a budget without an enforcement point is a wish
