token-efficiency

# Token Efficiency

Reduce output token waste and prevent iteration cycles that consume context.

## Trigger

Use when:
- Sessions feel expensive or slow
- Output is verbose with filler text
- Claude is re-reading files or iterating unnecessarily
- Setting up a new project for token-efficient work

## Anti-Sycophancy Rules

These patterns waste 30-60% of output tokens:

| Pattern | Example | Fix |
|---------|---------|-----|
| Sycophantic opener | "Sure! Great question!" | Delete. Lead with answer. |
| Prompt restatement | "You're asking about X..." | Delete. Answer directly. |
| Closing fluff | "Let me know if you need anything!" | Delete. Stop after the answer. |
| Unsolicited suggestions | "You might also want to..." | Delete unless asked. |
| AI disclaimers | "As an AI model..." | Delete entirely. |
| Verbose preambles | "I'll help you with that..." | Delete. Start with the action. |

## Tool-Call Budgets

Set explicit budgets by task complexity:

| Task Type | Tool-Call Budget | Wrap-Up At |
|-----------|-----------------|------------|
| Quick fix / lookup | 20 calls | 15 |
| Bug fix | 30 calls | 25 |
| Feature (small) | 50 calls | 40 |
| Feature (large) | 80 calls | 65 |
| Refactor | 50 calls | 40 |
| Exploration / research | 30 calls | 25 |

At the wrap-up threshold: commit progress, assess remaining work, decide whether to continue or start fresh.

## One-Pass Coding Discipline

For simple-to-medium tasks:

1. **Read all relevant files** including tests first
2. **Understand what tests assert** before coding
3. **Write complete solution in one pass** — not incrementally
4. **Run tests once** — if pass, STOP immediately
5. **If fail**: read the error, fix once, retest
6. **Never iterate** more than twice on the same failure — rethink approach
7. **Never refactor, improve, or polish passing code**

## Task Profiles

Switch profiles based on what you're doing:

### Coding Profile
- Return code first, explanation after (only if non-obvious)
- Simplest working solution, no over-engineering
- Read file before modifying — always
- No docstrings on unchanged code
- No error handling for impossible scenarios
- State bug, show fix, stop

### Agent/Pipeline Profile
- Structured output only: JSON, bullets, tables
- No prose unless targeting a human reader
- Every output must be parseable without post-processing
- Execute task, do not narrate actions
- Never invent file paths, API endpoints, or function names
- If unknown: return null or "UNKNOWN", never guess

### Analysis Profile
- Lead with finding, context and methodology after
- Tables and bullets over prose
- Numbers must include units
- Never fabricate data points
- Summary first (3 bullets max), caveats last

## Read-Before-Write Enforcement

Hard rules:
1. **Never write a file you haven't read** in this session
2. **Never re-read a file** already read unless it was modified
3. **Read tests before coding** — understand what passes before writing
4. **Read error output carefully** before attempting a fix

## ASCII-Only Output

Use ASCII characters only in all output:
- `--` not `—` (em dash)
- `"` not `"` `"` (smart quotes)
- `'` not `'` `'` (curly apostrophes)
- No emoji unless explicitly requested
- No Unicode decorators or special characters

This ensures clean copy-paste for code and compatibility with downstream systems.

## Measuring Impact

Track these metrics to measure token savings:
- **Output length**: average words per response (target: 30-50% reduction)
- **Tool calls per task**: should stay within budget tier
- **Re-read count**: should be near zero
- **Write-without-read count**: should be zero
- **Iteration cycles**: tests should pass in 1-2 attempts, not 5+

## Attribution

Token efficiency patterns adapted from [drona23/claude-token-efficient](https://github.com/drona23/claude-token-efficient) (MIT).