Token Waste Elimination

Token Waste Elimination

Memory files are LLM context, not human documentation. Every line costs tokens. Optimize for my consumption, not human readability.

Loading Tiers

Core Rules

Instructions thin, skills thick: Instructions = decision tables + routing. Skills = procedures + examples + references.

applyTo gates cost: Add applyTo to domain-specific instructions (file-type triggered). Omit for conversational/universal instructions.

No-applyTo != auto-load: Without applyTo, the description is always visible but I choose whether to load the body. Not deterministic.

Size Thresholds

Waste Patterns

Audit Procedure

1. Baseline: Run node .github/muscles/audit-token-waste.cjs for automated scan
2. Overlap: Find instructions with matching skills >50 lines. Trim to rules + routing pointer
3. Patterns: Fix every waste pattern hit (muscle --fix handles safe patterns automatically)
4. applyTo: Add globs to domain-specific instructions missing them
5. Always-on cost: Sum instruction descriptions + skill descriptions + copilot-instructions.md. Target: minimize
6. Prompt check: Prompts should be workflow steps only (20-40 lines). No code blocks or reference tables that exist in skills
7. Savings: Re-run muscle, compare before/after

Waste Triage Decision Table (AC3)

Not all scanner findings are actionable. Triage before fixing:

Rule: When uncertain, check if the content helps the LLM make better decisions. If yes → keep. If it's for human eyes only → remove or move.

When to Run

• After harvesting skills (inherited waste)
• Before a release (clean context = better responses)
• When response quality degrades (context bloat is often the cause)
• Quarterly maintenance (drift accumulates silently)

Audit Script Example

// .github/muscles/audit-token-waste.cjs
const fs = require('fs');
const path = require('path');

function auditInstructions(dir) {
  const files = fs.readdirSync(dir);
  const oversize = [];
  
  for (const file of files) {
    if (!file.endsWith('.instructions.md')) continue;
    const content = fs.readFileSync(path.join(dir, file), 'utf8');
    const lines = content.split('\n').length;
    
    // Check for matching skill
    const skillPath = `.github/skills/${file.replace('.instructions.md', '')}/SKILL.md`;
    const hasSkill = fs.existsSync(skillPath);
    const threshold = hasSkill ? 50 : 200;
    
    if (lines > threshold) {
      oversize.push({ file, lines, threshold, hasSkill });
    }
  }
  return oversize;
}

const results = auditInstructions('.github/instructions');
console.log(`Found ${results.length} oversize instructions`);
results.forEach(r => console.log(`  ${r.file}: ${r.lines} lines (max: ${r.threshold})`));

Optimization Before/After Example

## Before (45 tokens, wastes context)
When generating visualizations, use the chart-interpretation skill.
This skill provides patterns for reading charts and extracting insights.
The skill covers various chart types including bar charts, line charts, pie charts.

## After (12 tokens, same information)
Chart generation → chart-interpretation skill.

Quality Metrics