lmiranda
d90a8d05af
- New skill: token-budget-report.md with MCP overhead and skill loading estimation model based on known file sizes and static overhead tables - Sprint-plan displays token report after planning complete - Sprint-close displays token report after lessons captured - Visual-output.md updated with token report format - .gitignore exception for token-budget-report.md (not API tokens) Helps identify which phases and components consume the most context budget. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
116 lines
5.0 KiB
Markdown
116 lines
5.0 KiB
Markdown
---
|
||
description: Token consumption estimation model and display format for sprint workflows
|
||
---
|
||
|
||
# Token Budget Report
|
||
|
||
## Purpose
|
||
|
||
Provides directional token consumption estimates at sprint workflow boundaries. Not exact — Claude Code doesn't expose token metrics — but accurate enough to identify which phases and components consume the most context budget.
|
||
|
||
## When to Display
|
||
|
||
- End of `/sprint-plan` (after all issues created)
|
||
- End of `/sprint-close` (after lessons captured)
|
||
- On explicit request: `/sprint-status --tokens`
|
||
|
||
---
|
||
|
||
## Estimation Model
|
||
|
||
### MCP Tool Definitions (Static Overhead)
|
||
|
||
These are loaded once at session start. Update this table if MCP servers change.
|
||
|
||
| MCP Server | Default Tools | Est. Tokens | With Module Filter |
|
||
|------------|--------------|-------------|-------------------|
|
||
| netbox | 182 | ~19,810 | ~4,500 (dcim,ipam,virt,extras) |
|
||
| gitea | 36 | ~4,785 | — |
|
||
| data-platform | 32 | ~3,458 | — |
|
||
| viz-platform | 20 | ~3,055 | — |
|
||
| contract-validator | 8 | ~1,048 | — |
|
||
| **Total (default)** | **278** | **~32,156** | — |
|
||
| **Total (filtered)** | **~139** | **~16,846** | — |
|
||
|
||
### Skill Loading (Per Phase)
|
||
|
||
| Phase | Typical Skills Loaded | Est. Tokens |
|
||
|-------|----------------------|-------------|
|
||
| Planning (`/sprint-plan`) | mcp-tools-reference, label-taxonomy, sprint-planning, architecture-analysis, rfc-workflow | ~3,000–5,000 |
|
||
| Execution (`/sprint-start`) | mcp-tools-reference, branch-security, plan-then-batch | ~2,000–3,000 |
|
||
| Review (`/pm-review`) | mcp-tools-reference, review-checklist | ~1,500–2,500 |
|
||
| Close (`/sprint-close`) | mcp-tools-reference, sprint-lifecycle, lessons-learned | ~2,000–3,000 |
|
||
|
||
To get actual numbers: count characters in each skill file loaded during the phase, divide by 4.
|
||
|
||
### Agent Overhead
|
||
|
||
| Agent | Model | Est. Overhead per Invocation |
|
||
|-------|-------|------------------------------|
|
||
| Planner | sonnet | ~500 tokens (frontmatter + system context) |
|
||
| Orchestrator | sonnet | ~500 tokens |
|
||
| Executor | sonnet | ~400 tokens |
|
||
| Code Reviewer | sonnet | ~400 tokens |
|
||
|
||
---
|
||
|
||
## Display Format
|
||
|
||
```
|
||
+-- Token Budget Report -----------------------------------------------+
|
||
| Phase: [PLANNING / CLOSING] |
|
||
| Sprint: [Sprint Name] |
|
||
+----------------------------------------------------------------------+
|
||
| |
|
||
| MCP Overhead (session-wide): |
|
||
| netbox ........... ~4,500 tk (filtered: dcim,ipam,virt,extras) |
|
||
| gitea ............ ~4,785 tk |
|
||
| data-platform .... ~3,458 tk |
|
||
| viz-platform ..... ~3,055 tk |
|
||
| contract-valid ... ~1,048 tk |
|
||
| Subtotal ......... ~16,846 tk |
|
||
| |
|
||
| This Phase: |
|
||
| Skills loaded .... ~X,XXX tk (N files) |
|
||
| Agent overhead ... ~X,XXX tk (model: sonnet) |
|
||
| Command file ..... ~XXX tk |
|
||
| Subtotal ......... ~X,XXX tk |
|
||
| |
|
||
| Estimated Session Total: ~XX,XXX tk |
|
||
| Typical Claude Code Budget: ~200,000 tk |
|
||
| Estimated Usage: ~XX% |
|
||
| |
|
||
| Tip: Run `/doctor` for exact MCP overhead numbers. |
|
||
+----------------------------------------------------------------------+
|
||
```
|
||
|
||
---
|
||
|
||
## Instructions for the Agent
|
||
|
||
When generating this report:
|
||
|
||
1. **MCP Overhead**: List the MCP servers from `.mcp.json` and use the static token estimates from the table above. If `NETBOX_ENABLED_MODULES` is set in the environment, use the filtered estimate for netbox.
|
||
|
||
2. **Skills Loaded**: Count the skill files that were loaded (referenced in the command's "Skills Required" section). Estimate tokens by reading each file's character count and dividing by 4.
|
||
|
||
3. **Agent Overhead**: Use the table above based on which agent ran during this phase.
|
||
|
||
4. **Totals**: Sum the phase subtotal. Add to MCP overhead for session estimate.
|
||
|
||
5. **Percentage**: Express as a percentage of ~200,000 tokens (typical Claude Code context window).
|
||
|
||
---
|
||
|
||
## Accuracy Disclaimer
|
||
|
||
These are estimates based on known file sizes and static overhead tables. Actual consumption varies based on:
|
||
- Conversation length
|
||
- Tool call results (especially large grep/read outputs)
|
||
- File content read during the session
|
||
- Number of agent invocations
|
||
|
||
For exact MCP overhead, run `/doctor`.
|
||
|
||
This report helps identify which *components* consume the most budget — not the precise total.
|