Use when designing or debugging AI agent context strategies, optimizing token budgets, building context assembly pipelines, or diagnosing context-related failures (wrong answers from missing info, bloated context causing poor reasoning, conversation drift). Handles 5-level context hierarchy design, inverse context packing, token budget allocation, context window optimization, conversation summarization, and file-level inclusion/exclusion decisions. Do NOT use for prompt engineering (route to llm-engineer), agent architecture design (route to ai-engineer), or model selection (route to ai-engineer).
Use when designing or debugging AI agent context strategies, optimizing token budgets, building context assembly pipelines, or diagnosing context-related failures (wrong answers from missing info, bloated context causing poor reasoning, conversation drift). Handles 5-level context hierarchy design, inverse context packing, token budget allocation, context window optimization, conversation summarization, and file-level inclusion/exclusion decisions. Do NOT use for prompt engineering (route to llm-engineer), agent architecture design (route to ai-engineer), or model selection (route to ai-engineer).
works with Claude Code, Copilot CLI, Cursor, OpenClaw, Gemini CLI
Context Engineering
Portability target: Spec-level (runs on Claude Code, Copilot, Gemini CLI, Codex, Cursor). No vendor-specific frontmatter fields.
RESEARCH_PREREQUISITE — Execute Before Any Output
This is a HARD GATE. Do not produce ANY output, code, strategy, design, or recommendation without completing this research.
Before you act, you MUST execute every applicable research step. Research-before-acting is the difference between professional work and amateur guessing:
#
Research Step
Why It Matters
Where to Look
RP1
Verify domain currency. Check for breaking changes, deprecations, new standards, or version shifts since the knowledge cutoff.
[STALE_RISK] Outdated advice breaks real systems. API deprecations, framework version bumps, and security advisory changes happen continuously. Outputting based on stale knowledge damages credibility and produces broken results.
Official docs, changelogs, GitHub releases, RFC tracker
RP2
Audit the system or codebase. Read relevant files. Understand existing patterns, constraints, and architecture before proposing changes.
[CONTEXT_VIOLATION] Solutions that ignore existing patterns create technical debt. A change that contradicts the established architecture is worse than no change — it introduces inconsistency that compounds over time.
Cross-reference claims against authoritative sources. Every factual assertion needs a verifiable source. Mark each: [VERIFIED], [COMPUTED], or [ESTIMATED].
[HALLUCINATION_GUARD] Claims without sources are indistinguishable from hallucinations. The #1 cause of incorrect output is treating assumptions as facts. Source tagging prevents this.
Official documentation, peer-reviewed papers, RFCs, specifications
RP4
Identify known failure modes. Before recommending, list what commonly breaks. For each failure mode: trigger condition, detection signal, and mitigation.
[FAILURE_BLINDNESS] Every domain has known failure patterns. Output that doesn't address them is dangerously incomplete. If you cannot name 3+ failure modes for your recommendation, you don't understand it well enough to recommend it.
Quantify impact in concrete units. Replace abstract claims ("faster," "better," "more scalable") with exact numbers, even if estimated.
[VAGUENESS_PENALTY] "Faster" is unverifiable. "Reduces p95 latency from 340ms to 120ms (±15ms)" is verifiable. Abstract adjectives hide ignorance behind confidence. Concrete numbers expose gaps.
Benchmarks, production metrics, pricing data, published performance data
RP6
Map side effects and downstream impacts. What else breaks? Which dependencies are affected? Which downstream consumers need updating?
[CASCADE_BLINDNESS] Changes to one component ripple outward. A fix in module A can break module B that depends on A's old behavior. Map the blast radius before acting.
Dependency graph, cross-skill coordination table, API consumers list
RP7
Verify against non-negotiable quality gates. What are the minimum quality bars for this domain (accessibility, security, performance, accuracy, compliance)?
[QUALITY_FLOOR] Every domain has minimum standards below which output is invalid regardless of functionality. Missing WCAG AA = broken. Leaking credentials = broken. Silent data loss = broken.
Declare explicit limitations and edge cases. What does this NOT handle? What are the known boundaries? What scenarios are explicitly out of scope?
[SCOPE_HONESTY] Declaring limitations is a feature, not an admission of weakness. It prevents misuse, sets correct expectations, and demonstrates true understanding. Every solution has boundaries — naming them is professional.
This SKILL.md, domain literature, edge case databases
If you skip any of these research steps, you are not producing quality output — you are guessing with confidence. Guessing wastes time, breaks systems, and destroys trust. The references, ground rules, and decision trees in this skill exist specifically to prevent guessing. Use them.
Compliance: Research must be executed before any substantial output. For each step, document findings inline in your response using [RESEARCHED] marker: [RESEARCHED: RP1 — Domain verified against changelog v2.4. No breaking changes since cutoff.]. Partial research = partial quality. Zero research = zero credibility.
🔄 Iterative Research Loop — Research at EVERY Decision Point, Not Just Entry
The RP1-RP8 cycle above is NOT a one-time gate. It fires continuously at every material decision point throughout the workflow:
Loop
When It Fires
What Re-research Validates
Loop 0: Pre-Action
Before producing ANY output, code, strategy, or recommendation
At every adjustment, phase transition, scale-out, or significant state change
Has the context changed? Are the original assumptions still valid? Has new information invalidated the Loop 0 conclusions?
Loop 2: Pre-Exit
Before closing, handing off, escalating, or declaring completion
Is the deliverable complete by the quality gates defined in RP7? Are all limitations declared (RP8)? Have failure modes been addressed (RP4)?
Loop 3: Post-Action
After completion: compare expected vs. actual outcome
What was the efficiency ratio (actual / theoretical max)? What learnings emerged? What should be fed back into the pattern database for future decisions?
Integration into Core Workflow:
Every decision point in a skill's Core Workflow must be marked with:
[RESEARCH LOOP: Re-execute RP1-RP8 before proceeding to next phase]
This ensures the agent pauses to re-verify ALL research dimensions before making the next decision. A skill that only researches at entry and then operates on auto-pilot is a skill that makes decisions on stale context.
Markers for output: At each loop, the agent outputs: [RESEARCHED: Loop N — RP1-RP8 re-verified. Key delta from previous loop: ...]
Why this matters: A decision made in Loop 0 may be catastrophically wrong by Loop 2 because the context changed. Markets move. Requirements shift. Dependencies update. The research loop catches context drift before it becomes output error.
Compliance: Research must be executed before any substantial output AND re-executed at every decision point. For each research loop, document findings inline. Partial research = partial quality. Zero research = zero credibility. Stale research = dangerous confidence.
Anti-Hallucination
Rationalization
Reality
"Just include everything — the model has a 200K context window, it can handle it."
Every token beyond what the model needs dilutes signal-to-noise. GPT-4 accuracy on retrieval tasks drops 7-12% when context exceeds 70% of the window. You're not helping the model — you're drowning it in noise and paying for the privilege.
"Token costs aren't worth optimizing at our scale — we only spend $500/month."
A 10-dev team with 60% context pollution wastes $1,188/month in pure garbage tokens, plus 15-25% more turns per task from degraded reasoning. Your real cost is 3x what the bill shows.
"I know which files are important — I don't need a relevance scoring system."
The familiarity heuristic means you include files you know well even when irrelevant. A standard utils/ folder costs $375-$850/month in tokens the agent never reads. Your intuition is burning money.
"Prompt caching optimization is premature — we're just getting started."
Uncached tokens cost 25x more than cached tokens ($7.50/M vs $0.30/M). Delaying cache optimization on 500 requests/day burns $180/day — $3,960/month — on cache misses. "Getting started" is when optimization has the highest ROI.
"Context overflow won't happen to us — we use short conversations."
Context overflow doesn't announce itself. The agent "forgets" to write tests for new code, and you discover it in QA. The retrofit cost: 3 engineers × 2 days × $150/hr = $7,200 per incident. It already happened — you just haven't found the missing tests yet.
Ground Rules — Read Before Anything Else
#
Negative Constraint
Mechanical Trigger
Violation Response
1
NEVER include a source file without scoring its relevance first
ANCHOR to runtime versions before generating framework-specific code. Never generate Fastify/Express/Django/FastAPI/Prisma/SQLAlchemy API calls from training data alone — your training data may be stale.
Trigger: skill receives code-generation task involving framework-specific APIs → run scripts/runtime-version-detect.sh [project-root] --skill-context to detect installed versions → if detection succeeds, anchor all API calls to detected versions → if detection fails, request version info from user
STOP. Respond: "Detected: {runtime}@{version}, {frameworks}@{versions}. Anchoring all API calls to these versions. I will add // VERIFY: comments on any API call where the detected version is newer than my training cutoff."
R2
RUN the ROI Gate before any non-emergency code change. Every code change that is not (a) a security fix, (b) a compliance requirement, or (c) an active production incident must pass scripts/roi-gate.sh. If the gate returns negative, refuse to write the code.
Trigger: skill receives a code-generation or refactoring task that is NOT a security fix, compliance requirement, or production incident → estimate implementation cost in engineer-hours → compare against annual value of the change → if cost > value, gate fails
STOP. Respond: "ROI Gate analysis: This change costs approximately $[X] to implement but saves $[Y]/year. Payback period: [N] years. If payback > 2 years, I recommend declining this work. See scripts/roi-gate.sh for the full formula."
Admit uncertainty — never fabricate. If you're not certain about an API method, package version, configuration syntax, or command flag, say so explicitly: "I'm not certain this API exists in the latest version. Check the official docs at [URL]." Never invent a function signature or configuration key because it "seems right." Hallucinated code costs hours of debugging.
Flag your knowledge cutoff. If your training data predates the latest SDK release, framework version, or platform change, state your cutoff date and recommend verifying against current documentation. This is especially critical for rapidly evolving domains: cloud IAM policies, JS framework APIs, mobile OS capabilities, and SaaS pricing — all change quarterly or faster.
Never guess security configurations. If you're unsure about the correct CSP header value, OAuth flow parameter, or encryption algorithm choice, do NOT provide a "reasonable default." Say: "Security configurations must be verified against current best practices at [official source]. I cannot provide a definitive answer without current documentation."
Distinguish between what you know and what you infer. Explicitly mark statements as: [VERIFIED] — from official docs, [COMMON-PRACTICE] — widely used but not authoritative, [INFERRED] — your best guess based on patterns, [UNKNOWN] — you're unsure. This helps the user calibrate trust in your output.
The Expert's Mindset
Context engineering is not prompt engineering — it's information logistics. Masters understand three non-obvious truths:
1. More context degrades output. Every token beyond what the model needs dilutes signal-to-noise. Studies show GPT-4 accuracy on retrieval tasks drops 7-12% when context exceeds 70% of the window. The optimal band is 30-55% utilization.
2. Order matters more than content. The "lost-in-the-middle" phenomenon means information at positions 25-75% of context depth is 20-40% less likely to be attended to. Critical instructions go at the top; critical facts go at the bottom. Never bury a requirement in the middle.
3. Context is a cache, not a database. Treat the context window as an L1 cache with high miss penalty (~$0.01-0.05 per unnecessary token across a session). Every file included without purpose is a cache pollution event that cascades into degraded performance on subsequent turns.
Cognitive biases to guard against:
Completeness bias — "I'll just include everything to be safe" (exactly wrong)
Recency anchoring — over-weighting what was recently fixed vs. what's broken now
Familiarity heuristic — including files you know well even when irrelevant
Operating at Different Levels
Quick Scan (~30s)
Check the token budget dashboard. Verify cache hit rate > 60%. Confirm no Level 3-5 leak without Level 1-2 grounding. Run: python context_audit.py --quick
Standard Engagement (~5min)
Full context assembly pass: Level 1→2→3→4→5 with relevance scoring at each transition. Apply Inverse Context Packing. Validate against Ground Rules. Run: python context_audit.py --standard
Deep Dive (~30min)
Architecture review of the entire context pipeline. Includes: context window simulation with real workload traces, cache hit rate optimization, comparative testing with 3 different assembly strategies, and a dollar-cost projection for the next 10K requests.
When to Use
Triggers:
Agent produces wrong answer despite correct information being available in the repo
The design problem is the agent, not its context input
Model selection or provider comparison
ai-engineer
Context strategy follows model choice, not the reverse
Pure retrieval quality (embeddings, chunking)
ai-engineer
RAG plumbing, not context hierarchy design
Pure token-cost/caching/compression math on fixed content
token-efficiency
Cost optimization without context-structure decisions
If you are designing what goes INTO the context window — structure, priority, hierarchy, budget — this is the right skill. If you are tuning the model, the prompt text, or the retrieval stack — hand off.
"Designing from scratch" → Start at "Core Workflow" and proceed sequentially
Anti-Rationalization (QUICK)
AR-01 No Budget, No Context: You CANNOT assemble a context payload without declaring a token budget first. "The window is 200K, just fit what fits" is how budgets silently blow past 80% utilization and Level 1 rules get truncated. Declare the budget, then pack against it.
AR-02 No "Just-in-Case" Inclusion: You CANNOT include a file the task does not reference, no matter how cheap it feels. "It might be useful" is the sentence that burns $375-$850/month on files the agent never reads. Every token must earn its place via relevance score > 0.4.
AR-03 No Silent Truncation: You CANNOT let context overflow silently evict Level 1 (rules) or Level 4 (error output). "The model handled it" is a rationalization until the day it silently drops the "always write tests" rule. Hard cap at 80%; evict lowest-scoring Level 3 files first — explicitly, logged, not by overflow.
AR-04 No Cache-Prefix Churn: You CANNOT reorder, reformat, or annotate the stable prefix between requests. "It's just a comment" turns a $0.015 cached request into a $0.375 uncached one — 25×. Treat L1/L2 as byte-frozen; any change requires cache-freeze approval.
AR-05 No Unvalidated Compression: You CANNOT summarize conversation history or compress context without running a retention check. "The summary looked right" is how decisions and open questions get silently dropped. Validate ≥90% information retention before shipping a summary.
AR-06 No Handoff Without a Missing-Skill Check: You CANNOT hand off to a role whose skill does not exist in this library. "Close enough, route it anyway" creates non-deterministic agent behavior. If the target skill is missing, trigger the autonomous skill-creation protocol (Core Workflow, Phase 6) before handing off.
The counter-intuitive approach: start with everything, then surgically remove.
Algorithm: INVERSE_CONTEXT_PACKING
Input: candidate_files[], token_budget, relevance_threshold
Output: final_context[]
1. candidates ← ALL files in repo (recursive glob)
2. candidates ← SORT candidates BY relevance_score DESC
3. context ← [] , tokens_used ← 0
4. FOR each file IN candidates:
5. cost ← estimate_tokens(file)
6. IF tokens_used + cost > token_budget:
7. BREAK // budget exhausted; rest are excluded
8. IF relevance_score(file) < relevance_threshold:
9. CONTINUE // below quality bar
10. context.append(file)
11. tokens_used += cost
12. context ← DEDUPLICATE(context) // hash-based, content-aware
13. context ← COMPRESS(context) // strip comments, minify where safe
14. RETURN context
Why inverse? Traditional "additive" packing starts empty and adds — this biases toward files seen first. Inverse packing starts with the full ranked set and cuts from the bottom, ensuring priority files always make it in and lower-priority files never displace higher ones.
Deduplication: Hash every paragraph (not line). Merge paragraphs with Jaccard similarity > 0.85. This catches copy-pasted code blocks and duplicate error messages.
Compression: Strip comments from source files (unless the task is "add documentation"). Collapse whitespace in non-Python files. Truncate long string literals > 500 chars to "...[truncated {N} chars]".
Relevance scoring decay: Files that were included in the last 3 turns but never referenced get a 0.5x multiplier on their score. Files referenced by the agent get a 1.3x boost.
Step 5: Validation Pass
# Run before every context submission
python context_audit.py --check-ground-rules \
--max-tokens $(jq '.token_budget.L3' budget.json) \
--cache-hit-target 0.60 \
--dedup-threshold 0.85
Step 6: Autonomous Skill Creation on Handoff
[RESEARCH LOOP: Re-execute RP1-RP8 before proceeding — is the handoff target real, current, and truly missing from the library?]
When a downstream task requires a skill that does not exist in this library, do NOT degrade the handoff. Create the skill autonomously, then hand off.
#
Action
Verify
1
Detect the gap. The handoff target role/domain has no matching skill in skills/.
grep -rl "name: <target>" skills/ returns nothing; no >80% description-similar neighbor found
2
Duplicate check. Search for near-duplicates by name and description before creating. If an equivalent exists, extend it instead.
Validate. Run lint-template.py, lint-yaml.py, lint-markdown.py, and bash scripts/validate-skills.sh.
All gates pass; skill registers in the router
7
Hand off. Invoke the new skill's workflow for the original task, and record the creation in the State Log.
Downstream task completes using the created skill; State Log entry documents the gap + creation
Creation boundary: Only create a skill when (a) the task genuinely recurs or is consequential, (b) no existing skill covers it, and (c) you can fill it to the 10/10 bar. For one-off, low-stakes gaps, record the gap in the State Log and route to the nearest existing skill instead — creating a half-quality skill is worse than routing.
Handoff: Deliver the completed context strategy (or the new skill) to the consuming skill via cross-agent-skills-packaging conventions, and confirm the downstream skill's consumes_from includes this skill so the graph stays symmetric.
Best Practices
Declare token budget before assembly. Never build context without knowing your limit. Allocate a safety margin — never exceed 80% of the model's context window. The remaining 20% is buffer for conversation growth and unexpected file inclusion. Hard cap at 80% utilization prevents instruction truncation.
Use inverse context packing — start with everything, then surgically remove. Traditional additive packing biases toward files seen first. Start with all candidate files ranked by relevance, then cut from the bottom. This ensures priority files always make it in and lower-priority files never displace higher ones.
Mandatory relevance scoring for every file. Every file in context must earn its place. Score files by: edit recency (0.35), import distance from active files (0.30), semantic similarity to task (0.25), and file size penalty (0.10). Files below threshold 0.4 are excluded. No "just in case" inclusion.
Deterministic file ordering for prompt caching. Anthropic prompt caching requires stable prefix — exact byte match. Sort files by priority tier first, then alphabetically within tier. Static content (L1 rules, L2 specs) MUST be the prefix. Cache-friendly ordering saves 90%+ on input token costs for cached reads.
Deduplicate before compressing. Hash every paragraph, merge those with Jaccard similarity > 0.85. Deduplication catches copy-pasted code blocks and duplicate error messages before compression wastes tokens on them. Run dedup pass before any compression pass.
Apply relevance score decay for stale files. Files included in the last 3 turns but never referenced by the agent get a 0.5× multiplier on their score. Files actively referenced by the agent get a 1.3× boost. This self-correcting feedback loop keeps context fresh and relevant.
Summarize conversation history, don't accumulate it. After 10 turns, switch from raw conversation history to compressed summaries: decisions made, facts learned, and current state. Raw history grows unbounded; summaries stay at 3-15K tokens regardless of conversation length.
Never exclude error output (L4) without explicit override. The agent's error stack traces are the highest-signal content for debugging. Trimming to last 50 lines + stack trace only preserves the signal while managing token cost. Excluding L4 completely guarantees wrong fixes.
Measure cache hit rate continuously. Track cache hit rate over last 50 requests. Target > 60%. If cache hit rate drops, audit prefix stability — the L1/L2 content may have changed between requests. Cache misses on 50K token requests cost 25× more than cache hits.
Project dollar cost for every assembly strategy. Context engineering is cost engineering. Track $/request at current token prices. Compare strategies: how much does deduplication save? How much does summarization save? When the team sees context pollution costs $1,200/month in wasted tokens, priorities align.
Decision Trees
(QUICK)
1. Token Budget Allocation
Phase 1 — Gather:
Model name and context window size
Task complexity (simple/standard/complex)
Expected conversation length (turns)
Provider pricing ($/1K tokens input/output)
Phase 2 — Decide:
model_window > 150K?
├── YES → Use standard allocation, reserve 20% buffer
│ L1: 3% | L2: 10% | L3: 35% | L4: 5% | L5: 7% | Buffer: 20%
└── NO → Use tight allocation, reserve 15% buffer
L1: 4% | L2: 8% | L3: 25% | L4: 3% | L5: 5% | Buffer: 15%
Task is debugging?
├── YES → Shift 10% from L3 to L4
└── NO → Keep standard allocation
Expected turns > 20?
├── YES → Reserve additional 10% for L5 growth
└── NO → Standard L5 allocation
2. Context Level Selection
Phase 1 — Gather:
Task type (write code, debug, review, explain, refactor)
Agent state (cold start vs. mid-conversation)
Available artifacts (error logs, PRDs, ADRs)
Repository size (files count, total LOC)
Phase 2 — Decide:
Task is "write code"?
├── YES → Levels: L1 + L2 + L3 (no L4 unless errors exist)
└── NO → Continue
Task is "debug"?
├── YES → Levels: L1 + L3 + L4 (L2 only if specs explain expected behavior)
└── NO → Continue
Task is "review"?
├── YES → Levels: L1 + L2 + L3 (prioritize files in diff)
└── NO → All levels, standard allocation
Conversation turn > 10?
├── YES → Compress L5 to summary form (decisions + facts only)
└── NO → Include raw L5
3. File Inclusion Strategy
Phase 1 — Gather:
Dependency graph (import tree)
Recent git diff (what files changed)
Agent's edit history (what files it modified)
Task description (what the agent is asked to do)
Phase 2 — Decide:
File in git diff AND in edit history?
├── YES → Priority A (always include, full content)
└── NO → Continue
File is direct dependency of Priority A file?
├── YES → Priority B (include, may truncate if > 3K tokens)
└── NO → Continue
File shares module/package with Priority A?
├── YES → Priority C (include only function signatures + docstrings)
└── NO → Exclude unless relevance score > 0.7
Repository has > 200 files?
├── YES → Hard cap: max 15 Priority B + C files combined
└── NO → Soft cap: max 25 combined
4. Conversation Summarization
Phase 1 — Gather:
Full conversation history (all turns)
Agent's action log (tool calls, file edits)
Error occurrences and resolutions
Current task state
Phase 2 — Decide:
Turns > 15?
├── YES → Aggressive summarization
│ • Keep: decisions (what was chosen), facts (what was learned), state (what changed)
│ • Drop: tool call details older than 5 turns, resolved errors, intermediate reasoning
│ • Format: "Turn [N]: [Action] → [Outcome]"
└── NO → Continue
Turns 5-15?
├── YES → Light summarization
│ • Keep all decisions + facts, compress tool outputs > 2K tokens
└── NO → Keep raw history
Conversation crossed task boundary (new task started)?
├── YES → Full reset: summarize prior task as "Previously completed: [summary]"
└── NO → Incremental summarization
Agent response quality trend (human eval or heuristic)
Conversation turn count
Phase 2 — Decide:
Context utilization > 85%?
├── YES → IMMEDIATE RESET. Compress L5, evict lowest-score L3 files.
└── NO → Continue
Cache hit rate < 40% for 5+ consecutive turns?
├── YES → Restructure prefix. Move static content (rules, specs) to stable prefix.
└── NO → Continue
Agent made same mistake 3 times?
├── YES → Context pollution suspected. Purge L4, re-include L2 specs.
└── NO → Continue
Turn count > 30?
├── YES → Forced L5 compression regardless of utilization.
└── NO → No action
6. Cross-File Dependency Resolution
Phase 1 — Gather:
Import graph from static analysis (pycg, madge, depcruise)
Git blame for each candidate file (who/last modified)
File sizes (token estimates)
Test coverage data per file
Phase 2 — Decide:
File imported by > 5 Priority A files?
├── YES → Include as Priority B even if not in diff
└── NO → Continue
File is test file for a Priority A source file?
├── YES → Include if task is "debug" or "refactor", exclude otherwise
└── NO → Continue
File has 0% test coverage AND is Priority C?
├── YES → Drop from context (unreliable signal, risk of confusion)
└── NO → Keep at assigned priority
File size > 5K tokens?
├── YES → Include only: imports + function signatures + class definitions (no bodies)
└── NO → Include full content
Error Recovery
(STANDARD)
If a command or approach fails, follow this escalation path before giving up:
Symptom
First Action
If That Fails
Last Resort
Tool/command not found
Check installation: which [tool] or [tool] --version. Install via package manager (brew install, npm install -g, pip install)
Check PATH: echo $PATH. Verify the tool binary is in a PATH directory. Symlink or update PATH if installed but unreachable
Use a functionally equivalent alternative tool. If rg is unavailable, use grep -r. If gh is unavailable, use git directly or the GitHub API via curl
Permission denied
Check ownership: ls -la [path]. Fix with chmod or sudo if appropriate. For API errors (401/403), verify credentials haven't expired: echo $TOKEN or check ~/.netrc
Refresh credentials: re-authenticate with the service. For file permissions, check if the file is locked by another process: lsof [path]
Request elevated permissions or use a different authentication method (token vs password, SSH key vs HTTPS)
Command hangs or times out
Kill the process: Ctrl+C. Re-run with a timeout: timeout 30 [command] or gtimeout on macOS. Check system resources: top, df -h, netstat -an
Add verbose/debug flags: --verbose, --debug, -v. Check logs: tail -f [logfile]. Reduce scope: process fewer files, query a smaller time range, limit concurrency
Split the work into smaller batches. Implement a retry loop with exponential backoff (1s, 2s, 4s, 8s). If the issue is network-related, add --retry 3 or equivalent
Unexpected output or error message
Read the error message completely — the solution is often in the last 3 lines. Search the exact error: grep -r "[error text]" in the repo to find prior occurrences
Check GitHub issues for the tool: gh issue list --repo owner/repo --search "[error keyword]". Check Stack Overflow
Simplify the approach. If the complex one-liner fails, break it into 3 sequential commands. If the specialized tool fails, use a more basic tool with more steps
Data integrity concern (wrong output, silent failure)
Verify with a manual check: compare output against a known-correct baseline. Add assertions: `[command]
grep -q "[expected]" && echo "OK"
Hard failure boundary: If 3 different approaches all fail, STOP. Do not iterate infinitely. Log what was tried, capture the error output, and report the blocking issue with full context. Move to the next independent task rather than blocking all progress on one failure.
Error Decoder
Symptom
Root Cause
Fix
Lesson
Agent "forgets" instructions after turn 12 and stops running tests
Context window exceeded 90% utilization; Level 1 rules (which include "always run tests") were truncated. The agent literally cannot see the instruction anymore.
Hard cap context utilization at 80% of model window. Evict lowest-scoring Level 3 files before touching Level 1 content. Monitor context utilization per turn; alert if > 80%.
Context truncation is invisible — the agent doesn't know it forgot something. It just stops doing it. The most critical instructions (L1) must be protected from eviction by budget hard caps and tier-based eviction priority.
Cache hit rate drops from 70% to 10% overnight with no code changes
Context assembly order changed — a new file was added to L1 (rules), shifting the byte prefix. Anthropic prompt caching requires exact byte match from position 0.
Audit L1/L2 content for changes. Keep static content truly static — never reorder, never reformat, never add comments to L1 between requests. Implement a "cache prefix freeze" — L1 content changes require explicit approval.
Prompt caching is brittle — any change to the prefix breaks caching for the entire request. A 5-character comment added to a rules file can turn $0.015/request into $0.375/request. 25× cost increase from a single line change.
Agent proposes a fix that creates a new bug — it never saw the error stack trace
Level 4 (error output) was excluded from context to save tokens. The agent worked from the symptom description alone, missing the specific error code, file path, and line number in the stack trace.
Never exclude Level 4 without explicit override. Trim to last 50 lines + stack trace only — preserve signal, manage cost. Add a ground rule: "Error stack traces are always higher priority than 20% additional source files."
Debugging without error traces is like surgery blindfolded. The 500-1,000 tokens saved by excluding L4 cost 4-8 hours of engineering time implementing the wrong fix. Token savings that cost engineering hours are not savings.
Token costs grow 3× over a month with no increase in agent usage
Relevance scoring is not pruning stale files. Files from early turns remain in context indefinitely. Conversation history (L5) is accumulating raw, not summarizing after turn 10.
Apply relevance score decay: files unreferenced for 3+ turns get 0.5× multiplier. Switch to conversation summaries after 10 turns. Run python context_audit.py --cost-trend weekly and alert on > 20% growth.
Context cost growth is gradual and invisible — there's no error, no crash, no alert. It creeps up 5% per week until your monthly LLM bill is 3× what it should be. Cost trend monitoring catches the creep before the bill does.
Different developers on the same project get different agent behavior for the same task
Context assembly is developer-specific — different file selection, different ordering, different summarization. No shared context strategy or budget enforcement.
Define a project-level context strategy: token budget per task type, relevance scoring weights, file ordering rules. Enforce via context_audit.py --check-compliance in CI. Share strategy as committed config.
Context assembly is infrastructure, not personal preference. When each developer builds context differently, you have N different agents instead of 1 reliable one. Standardized context strategy makes agent behavior reproducible and debuggable.
Context pollution from a single large auto-generated file (e.g., 5K-line package-lock.json)
File size penalty in relevance scoring is too weak — the 0.10 weight allows 5K-token auto-generated files to enter context if they have high import proximity.
Increase file size penalty weight for auto-generated files. Use a file_type_blacklist for known noisy files: package-lock.json, yarn.lock, Cargo.lock, *.min.js, *.pyc. These files are human-unreadable and waste context budget.
Not all files are created equal for context. Auto-generated lockfiles, minified bundles, and compiled binaries are token sinks with zero information density. A blacklist is more effective than trying to score them into exclusion — just never include them.
Conversation has > 3 context reset triggers in one session
Counter in context_audit.log
Escalates to full manual review; pauses automated context assembly
State Log
This skill maintains a decision ledger to prevent context drift and ensure recall across sessions. Every major architectural choice, constraint decision, and trade-off must be recorded so that subsequent agents (or future sessions) can recover context without replaying the entire conversation.
What Good Looks Like
Before (poor context engineering):
Turn 1: Agent receives 45K tokens → 18 source files, full conversation history
Turn 5: Agent receives 67K tokens → 24 source files, raw history (12 turns)
Turn 10: Agent receives 112K tokens → 31 source files, raw history (22 turns)
Turn 15: Agent receives 158K tokens → context overflow, instructions truncated
Result: Agent "forgets" to run tests. Cost: $0.47 for this session alone.
Budget calibration drill: Take a real agent trace. Manually score each file for relevance. Compare your judgment against the automated scorer. Calibrate until agreement > 85%.
Summarization quality check: Take a 20-turn conversation. Write a summary in exactly 500 tokens. Have another agent try to answer a question about turn 12 using only your summary. Iterate until accuracy > 90%.
Cache structure optimization: Take 100 agent requests. Identify the largest stable prefix that can be cached. Measure cost savings from prompt caching. Target: > 40% cost reduction.
Context pollution audit: Run an agent on a known task. After each turn, check if any included file was never referenced. Target: < 15% unreferenced files per turn.
Cross-model portability test: Take a context assembly tuned for Claude 200K. Adapt it for GPT-4o 128K without losing task completion quality. Document every compression decision.
Anti-Patterns (STANDARD)
❌ Anti-Pattern
✅ Do This Instead
❌ Additive context packing — start empty, add files reactively as the agent asks. By turn 10, 60% of 30+ files were only relevant to turn 2.
✅ Inverse packing — rank all candidates by relevance, include top-N within budget, evict files unreferenced for 3+ turns. Start fresh from the ranked set each turn.
❌ Static token budget for all task types — debugging, feature work, code review all get the same 50% L3 allocation.
❌ Including entire directories "just in case" — a whole utils/ folder because the agent "might need something." Burns $375-$850/month on unread files.
✅ Dependency-graph inclusion — only include files reachable from files the agent is actively editing; relevance-score every candidate ≥ 0.4.
❌ Compressing without validation — strip comments and summarize history, then discover the omitted error code was the answer.
✅ Validate retention ≥ 90% — write a 500-token summary, have a fresh agent answer questions about turn 12 from it alone; iterate until accurate.
❌ Ignoring cache-prefix stability — file ordering varies per request; every request is a cache miss at 25× the cost ($0.375 vs $0.015 on 50K tokens).
✅ Deterministic ordering — priority tier → alphabetical within tier; freeze L1/L2 byte-for-byte; measure hit rate > 60% continuously.
1. Context Pollution: The Silent Killer ($1,200/month)
A 10-developer team running 50 agent calls/day each at $0.03/call. If 60% of context tokens are irrelevant (pollution), that's $0.018 wasted per call × 50 calls × 22 days × 10 devs = $1,188/month in wasted tokens. Worse: polluted context causes 15-25% more turns per task due to degraded reasoning, doubling the real cost. Fix: mandatory relevance scoring before inclusion. Every file in context must earn its place.
2. Token Waste from Including Irrelevant Files ($850/month)
Common pattern: including entire utils/ directory "just in case." A typical utils/ folder is 15-30 files averaging 500 tokens each = 7,500-15,000 tokens. At Anthropic's $3/M input tokens, that's $0.02-0.05 per request. Across 15,000 requests/month (team of 8): $375-$850/month burned on files the agent never reads. Fix: dependency-graph-based inclusion. Only include files reachable from the files the agent is actively editing.
A production debugging session where the agent doesn't receive the error stack trace (Level 4 excluded) proposes a fix that creates a new bug. Engineer spends 4 hours implementing the wrong fix, then 2 hours reverting, then 2 hours re-debugging. At $200/hr fully loaded: $1,600 in wasted engineering time. If this happens twice a month: $3,200/month. Fix: Ground Rule #4 — never exclude Level 4 without explicit override.
Agent operating near context window limit (90%+ utilization) has instructions from Level 1 truncated. The agent "forgets" it must write tests for all new code. A feature ships without tests, discovered in QA. 3 engineers spend 2 days retrofitting tests: 3 × 16hrs × $150/hr = $7,200 one-time cost. If this pattern repeats quarterly: $2,400/month amortized. Fix: Ground Rule #3 — hard cap at 80% utilization. Never let the buffer drop below 20%.
5. Prompt Caching Failures ($1,500/month)
Anthropic prompt caching requires a stable prefix (exact byte match). If context assembly varies file ordering between requests, every request becomes a cache miss. At $7.50/M input tokens (uncached) vs $0.30/M (cached) for cached read tokens, a 50K token request costs $0.375 uncached vs $0.015 cached. For 500 requests/day: uncached = $187.50/day, cached = $7.50/day. Difference: $180/day or $3,960/month. Even a 50% cache hit rate saves $1,980/month. Fix: deterministic file ordering in context assembly. Always sort by priority tier first, then alphabetically within tier. Static content (L1, L2) MUST be the prefix.
Production Checklist (STANDARD)
Before any context assembly strategy reaches production, verify:
CR1: Token budget declared and enforced — Verification: jq '.token_budget' context.json returns valid allocation per task type
CR2: Context utilization < 80% of model window — Verification: python context_audit.py --check-usage passes
CR3: All Level 3 files have relevance scores > 0.4 — Verification: python context_audit.py --check-scores passes
CR5: Conversation history (L5) summarized, not raw, if turns > 10 — Verification: raw turn count ≤ 10 in payload; summary preserves all decisions
CR6: Level 1 content (rules) byte-identical to previous request — cache-friendly prefix preserved — Verification: diff against previous L1 prefix returns zero changes
CR7: File ordering deterministic: priority tier → alphabetical within tier — Verification: two assemblies of same input produce byte-identical payloads
CR8: No stale file included without being referenced for 3+ turns — Verification: stale-file eviction log shows files removed after 3 idle turns
CR9: Error output (L4) trimmed to last 50 lines + stack trace — never excluded entirely — Verification: L4 never exceeds 5% of total budget; stack trace always present
CR10: Cache hit rate measured and > 60% over last 50 requests — Verification: python context_audit.py --check-cache reports ≥ 60%; prefix freeze enforced
CR11: Dollar-cost projection updated and compared against alternatives — Verification: cost dashboard shows projected vs actual; trend flat or declining
CR12: Task-type-specific budget allocation defined — Verification: debugging, feature implementation, code review, exploration each have caps
CR13: Relevance score decay active — Verification: files unreferenced 3+ turns get 0.5× multiplier; decay log present
CR14: Compression validation completed — Verification: summary quality > 90% accuracy on information retention test
CR15: Ground Rules 1-8 all passing — Verification: python context_audit.py --check-ground-rules returns zero failures
CR16: Handoff skill gaps resolved — Verification: any required downstream skill missing from skills/ was created via Step 6 or the gap is recorded in the State Log
Gotchas
Gotcha
Cost
Fix
Context window exceeds 90% utilization — Level 1 rules (including "always run tests") get silently truncated
$100K-$500K in shipping untested code from invisible instruction loss
Hard cap context utilization at 80% of model window. Evict lowest-scoring Level 3 files before touching Level 1 content. Monitor context utilization per turn; alert if > 80%.
Cache prefix changes by 5 characters — cache hit rate drops from 70% to 10%, costs jump 25×
$100K-$400K/year in unnecessary token costs from cache busting
Freeze L1/L2 content ordering. Never reorder, reformat, or add comments to stable prefix between requests. Changes require explicit cache-prefix freeze approval. A 5-char comment can turn $0.015/request into $0.375/request.
Excluding error output (L4) to save tokens — agent works from symptom description, implements wrong fix
$50K-$200K/incident in engineering hours wasted on wrong solutions
Never exclude Level 4 without explicit override. Trim to last 50 lines + stack trace only. Add ground rule: "Error stack traces are always higher priority than 20% additional source files."
Relevance scoring doesn't prune stale files — costs grow 3× month over month
$50K-$250K/year in unchecked context cost growth
Apply relevance score decay: files unreferenced for 3+ turns get 0.5× multiplier. Switch to conversation summaries after 10 turns. Run cost trend audit weekly. Alert on > 20% cost growth.
Verification
#
Complete when...
Verify
☐
Complete when the token budget is declared and enforced: jq '.token_budget' context.json returns a valid allocation with per-level caps that sum to ≤ 80% of the model's context window
Verify python context_audit.py --check-usage reports utilization < 80%; budget config is version-controlled and reviewed on every change
☐
Complete when all Level 3 files have relevance scores > 0.4 and no file remains in context that hasn't been referenced for 3+ turns (relevance decay of 0.5× applied to stale files)
Verify python context_audit.py --check-scores returns zero files below threshold; stale-file eviction log shows files removed after 3 idle turns
☐
Complete when deduplication pass is complete with < 5% duplicate rate — no duplicated file paths, near-duplicate snippets, or redundant information across levels
Verify grep -c "DUPLICATE" context_audit.log returns ≤ 2% of total context items; dedup hash detects near-duplicates, not just exact matches
☐
Complete when conversation history (Level 5) is summarized (not raw) when turns exceed 10 — preserving decisions, unresolved questions, and state changes while compressing verbatim exchanges
Verify raw turn count ≤ 10 in context payload; summary preserves all decision points and open questions; summarization doesn't introduce factual drift
☐
Complete when Level 1 content (ground rules, core instructions) is byte-for-byte identical to the previous request — no reordering, reformatting, or comment changes that would bust the cache prefix
Verify diff against previous request's L1 prefix returns zero changes; any L1 modification has an explicit cache-freeze approval documented in the commit
☐
Complete when file ordering is deterministic: priority tier first (L1 → L2 → L3 → L4 → L5), then alphabetical within each tier — same input produces identical context assembly every time
Verify two consecutive assemblies of the same input produce byte-identical context payloads; ordering is enforced by the assembler, not left to sorting ambiguity
☐
Complete when error output (Level 4) is trimmed to the last 50 lines plus the full stack trace — never excluded entirely, but never included as a raw multi-thousand-line dump
Verify error truncation preserves stack trace and surrounding context; L4 never exceeds 5% of total context budget; stack trace lines are always higher priority than additional source files
☐
Complete when cache hit rate is > 60% over the last 50 requests, measured by prefix match length — and any 5-char change to stable prefix is flagged as a cache-busting risk requiring approval
Verify python context_audit.py --check-cache reports hit rate ≥ 60%; cache-bust alerts fire on any prefix modification; cost-per-request is tracked and compared to baseline
☐
Complete when Ground Rules 1-8 are all passing: python context_audit.py --check-ground-rules returns zero failures, confirming no rule truncation, level misordering, or priority inversion
Verify automated ground-rule check is in CI; any ground-rule failure blocks deployment; rule positions in the assembled context match the canonical ordering
☐
Complete when the dollar-cost projection is updated for the current assembly strategy and compared against the previous week's actual cost — alert fires if cost growth exceeds 20% week-over-week
Verify cost dashboard shows projected vs actual; trend line is flat or declining; alert threshold is configured and tested with a simulated spike
Verification Guardrails
Before delivering work, verify: self-check against What Good Looks Like, no broken references, continuity with State Log, no fabricated APIs/versions/capabilities, Error Recovery paths exercised, cross-skill dependencies satisfied. If any fail, revise before delivering.
