| name | context-budget |
| description | Analyze and optimize token usage — cost summary, cost per agent, per story, per gate, cache hit rates, and recommendations for context reduction. Use --summary for a quick cost overview. |
Context Budget Skill
Analyze token consumption across the build and recommend optimizations to reduce cost and improve efficiency.
Usage
/context-budget # full analysis + recommendations
/context-budget --summary # quick cost summary only (replaces former /cost)
Run anytime during or after a build.
Prerequisites
cost-log.json exists with token usage entries from the build.
Step 1 — Read Cost Log
Read cost-log.json. Parse entries for:
- Token counts (input, output, cache_read, cache_write) per interaction
- Agent type (architect, generator, evaluator, reviewer, etc.)
- Story/task identifier
- Gate stage (test, lint, coverage, architecture, evaluator, reviewer, ui-standards, security)
- Timestamp and duration
Step 2 — Calculate Usage by Agent Type
Aggregate tokens per agent:
- Total input tokens, output tokens, cache tokens
- Average tokens per invocation
- Number of invocations
- Most expensive single invocation
Step 3 — Calculate Usage by Story
Aggregate tokens per story/task:
- Total cost per story
- Breakdown by gate stage
- Number of GAN iterations (generator-evaluator cycles)
- Identify stories with unusually high token consumption
Step 4 — Calculate Usage by Gate
Aggregate tokens per gate stage:
- Total cost per gate across all stories
- Average cost per gate invocation
- Pass/fail rate per gate (failed gates cost extra due to rework)
Step 5 — Check Prompt Caching Opportunities
Analyze cache performance:
- Cache hit rate (cache_read / total_input)
- Identify large uncached prompts that repeat across invocations
- Estimate savings from improved caching
Step 6 — Recommend Context Reduction Strategies
Based on analysis, recommend:
- Reducing file loading scope (e.g., "load only owned files instead of full component map")
- Splitting large stories to reduce per-invocation context
- Improving cache hit rate via prompt structure changes
- Reducing GAN iterations via better generator prompts
- Skipping unnecessary gate stages for trivial changes
Step 7 — Generate Cost Projection
For remaining work:
- Estimate tokens needed based on remaining stories
- Project total build cost
- Compare against budget if configured in manifest
Output Format
Print report to console (not saved to file):
=== Context Budget Report ===
## Current Usage
- Total tokens: X (input: X, output: X, cached: X)
- Cache hit rate: X%
- Total cost estimate: $X.XX
## By Agent
| Agent | Tokens | Invocations | Avg/Call |
|-------------|----------|-------------|----------|
| generator | X | X | X |
| evaluator | X | X | X |
| ... | ... | ... | ... |
## By Story (top 5 most expensive)
| Story | Tokens | GAN Cycles | Gate Fails |
|-------------|----------|-------------|------------|
| ... | ... | ... | ... |
## Recommendations
- [specific, actionable recommendations]
## Projection
- Remaining stories: X
- Estimated remaining tokens: X
- Projected total cost: $X.XX
Quick Summary Mode (--summary)
When invoked with --summary, skip Steps 3-7 and print only a compact cost overview:
Mode: {mode} (budget: ${low}-${high})
Model routing: {strategy} ({local_model_name if applicable})
Agent spawns: {count}
Estimated total: ${amount} ({pct}% of budget ceiling)
Breakdown: Opus {n} spawns (${amount}), Sonnet {n} spawns (${amount}), Local {n} spawns ($0.00)
Top consumers: {agent1} (${amount}), {agent2} (${amount}), {agent3} (${amount})
Also read execution.model_routing from project-manifest.json and display the routing strategy. When strategy is local-only, show:
Model routing: local-only (Qwen3-Coder-480B-A35B-Instruct via vLLM)
Estimated API cost: $0.00 (all local)
Note: Local inference has compute cost (GPU time) not tracked here.
Estimation Method
| Model | Input $/1M tokens | Output $/1M tokens | Avg input | Avg output |
|---|
| Opus | $15 | $75 | 15K tokens | 5K tokens |
| Sonnet | $3 | $15 | 10K tokens | 3K tokens |
| Local | $0 | $0 | N/A | N/A |
Caveat: These are rough directional estimates, not actual billing. Token counts are approximated. Actual costs depend on prompt caching, system prompt sharing, and output length variation.
Budget Ranges by Mode
| Mode | Low | High |
|---|
| Full | $100 | $300 |
| Lean | $30 | $80 |
| Solo | $5 | $15 |
| Turbo | $30 | $50 |
Gotchas
- Report only, no file output. This skill prints to console for immediate review. Recommendations are for manifest tuning, not automated changes.
- Cache hit rate depends on prompt structure. Small changes to system prompts can invalidate the entire cache.
- GAN iterations are the biggest cost driver. Focus optimization on reducing evaluator failures, not on trimming individual prompts.
