/token-report - Generate Token Summary Report
Usage
/token-report STORY-XXX
Arguments
- STORY-XXX — story ID (e.g., STORY-001, WRKF-1021)
Locate Story Directory
The story can be in one of these directories:
-
plans/stories/backlog/STORY-XXX/
-
plans/stories/elaboration/STORY-XXX/
-
plans/stories/ready-to-work/STORY-XXX/
-
plans/stories/in-progress/STORY-XXX/
-
plans/stories/QA/STORY-XXX/
-
plans/stories/UAT/STORY-XXX/
Search these directories in order to find the story.
Preconditions
-
KB must have token entries for the story (logged via /token-log )
-
If no entries found: STOP and report "No token entries found in KB for STORY-XXX — run /token-log phases first"
Task
-
Query KB for token entries: kb_search({ type: "token_usage", story_id: "STORY-XXX" }) // Returns array of { phase, input_tokens, output_tokens, timestamp }
-
Aggregate phase data
-
Generate <story-directory>/_implementation/TOKEN-SUMMARY.md
Token Summary Format
Token Summary - STORY-XXX
Generated: YYYY-MM-DD HH:MM
Phase Breakdown
| Phase | Input | Output | Total | % of Total |
|---|---|---|---|---|
| pm-generate | 15,000 | 5,000 | 20,000 | 12.6% |
| elaboration | 20,000 | 2,000 | 22,000 | 13.8% |
| dev-implementation | 80,000 | 37,000 | 117,000 | 73.6% |
| Total | 115,000 | 44,000 | 159,000 | 100% |
Cost Estimate
Using Claude Opus pricing:
- Input: $0.003 / 1K tokens
- Output: $0.015 / 1K tokens
| Category | Tokens | Cost |
|---|---|---|
| Input | 115,000 | $0.35 |
| Output | 44,000 | $0.66 |
| Total | 159,000 | $1.01 |
High-Cost Operations
Phases exceeding 30,000 tokens:
| Phase | Total Tokens | Notes |
|---|---|---|
| dev-implementation | 117,000 | Primary implementation work |
Comparison to Typical Budget
| Metric | This Story | Typical | Variance |
|---|---|---|---|
| PM phases | 42,000 | 50,000 | -16% |
| Dev phases | 117,000 | 100,000 | +17% |
| Total | 159,000 | 200,000 | -21% |
Timeline
| First Entry | Last Entry | Duration |
|---|---|---|
| YYYY-MM-DD HH:MM | YYYY-MM-DD HH:MM | X hours |
Raw Log
(From KB storyTokenUsage)
| Timestamp | Phase | Input | Output | Total | Cumulative |
|---|---|---|---|---|---|
| ... |
Calculations
Percentage of Total:
phase_percent = (phase_total / grand_total) * 100
Cost Estimate:
input_cost = (input_tokens / 1000) * 0.003 output_cost = (output_tokens / 1000) * 0.015 total_cost = input_cost + output_cost
Typical Budget Reference:
Phase Group Typical Total
PM phases (pm-generate, pm-fix, elaboration) 50,000
Dev phases (dev-*, code-review) 100,000
QA phases (qa-verify) 50,000
Full story lifecycle 200,000
Variance:
variance_percent = ((actual - typical) / typical) * 100
High-Cost Threshold
Flag phases exceeding 30,000 tokens as "high-cost operations"
Phase groups for analysis:
-
PM: pm-generate, pm-fix
-
Elaboration: elaboration
-
Dev Setup: dev-setup
-
Dev Planning: dev-planning
-
Dev Implementation: dev-implementation (often highest)
-
Dev Verification: dev-verification
-
Dev Documentation: dev-documentation
-
Review: code-review
-
QA: qa-verify
-
Fix: dev-fix
Output
After generating the summary, report:
Token summary generated for STORY-XXX:
Total: XXX,XXX tokens (~$X.XX) Phases: N phases logged Highest: phase-name (XX,XXX tokens) Status: [Under budget / On budget / Over budget]
File: plans/stories/<status>/STORY-XXX/_implementation/TOKEN-SUMMARY.md
Error Handling
If KB returns no entries for the story:
-
Report: "No token entries found in KB for STORY-XXX"
-
Suggest running /token-log for each phase
If KB query fails:
-
Report the error message
-
Suggest checking that the KB MCP server is running