gh-tstomtimes-orchestra/skills/core/token-efficiency.md

# Token Efficiency Skill

**Purpose**: Minimize unnecessary token usage while maintaining code quality and thoroughness.

## Core Principles

### 1. Targeted Search, Not Exploration

**Always prefer specific over general:**
- ✅ `Glob("**/auth/login.ts")` - Exact file
- ✅ `Grep("function handleAuth", type="ts")` - Specific pattern with file type
- ❌ `Glob("**/*.ts")` - Too broad
- ❌ Reading entire directories without filtering

### 2. Read Only What You Need

**Before reading a file, ask:**
- Do I need the entire file, or just specific sections?
- Can I use grep to find the relevant parts first?
- Has this file already been read in the conversation?

**Use Read with limits:**
```
Read(file_path, offset=100, limit=50)  # Only read 50 lines starting at line 100
```

### 3. Search Hierarchy (Most to Least Efficient)

1. **Known location**: Direct file read if path is known
2. **Pattern matching**: Glob with specific patterns
3. **Keyword search**: Grep for specific terms
4. **Contextual search**: Grep with -A/-B flags for context
5. **Agent search**: Task tool with Explore agent (last resort)

### 4. Incremental Discovery

**Don't gather everything upfront:**
```
Bad approach:
1. Read all files in src/
2. Read all test files
3. Read all config files
4. Then start implementation

Good approach:
1. Read the specific file to modify
2. Implement the change
3. Only read related files if needed during implementation
4. Read tests only when writing test updates
```

### 5. Scope Boundaries

**Set clear limits:**
- Maximum files to examine: 5-10 for most tasks
- Maximum file size to read fully: ~500 lines
- Large files: Use offset/limit or grep first
- Stop once you have sufficient information

### 6. Efficient Grep Usage

**Use appropriate output modes:**
- `files_with_matches`: Just need to know if pattern exists
- `count`: Just need to know how many matches
- `content`: Need to see actual matches (use head_limit)

**Add context only when needed:**
```
Grep("error handler", output_mode="content", -C=3, head_limit=10)
# Only 10 results with 3 lines of context each
```

### 7. Avoid Redundant Operations

**Check conversation history first:**
- Don't re-read files already examined
- Reference previous findings instead of re-searching
- Build on existing knowledge

### 8. Model Selection for Task Tool

**Choose the right model for the job:**
```
# Simple, well-defined task
Task(description="...", model="haiku", prompt="...")

# Default for most tasks (good balance)
Task(description="...", model="sonnet", prompt="...")

# Complex reasoning required (use sparingly)
Task(description="...", model="opus", prompt="...")
```

## Practical Examples

### Example 1: Adding a New Function

**Inefficient approach:**
```
1. Read entire src/ directory
2. Read all related files
3. Search for all similar patterns
4. Then implement
```

**Efficient approach:**
```
1. Grep for similar function names (files_with_matches)
2. Read ONE example file
3. Implement based on that pattern
4. Only read more if the first example is unclear
```

### Example 2: Bug Investigation

**Inefficient approach:**
```
1. Read all files that might be related
2. Search entire codebase for error messages
3. Check all test files
```

**Efficient approach:**
```
1. Grep for the specific error message
2. Read only the files containing that error
3. Check git blame if needed to understand context
4. Read tests only for files being modified
```

### Example 3: Code Review

**Inefficient approach:**
```
1. Read all files in the PR
2. Read all related test files
3. Read all documentation
4. Then provide feedback
```

**Efficient approach:**
```
1. Use git diff to see only changed lines
2. Read changed files with offset/limit to focus on modifications
3. Grep for test coverage of changed functions
4. Request summaries instead of reading full docs
```

## Token Budget Estimates

**Quick reference for delegation:**

| Task Type | Estimated Tokens | Recommended Model |
|-----------|------------------|-------------------|
| Simple bug fix | 2-5K | haiku |
| New feature (small) | 5-10K | haiku |
| New feature (medium) | 10-20K | sonnet |
| Architecture design | 20-30K | sonnet |
| Complex refactoring | 30-50K | sonnet |
| Full system review | Split into chunks | sonnet |

## Red Flags (Stop and Optimize)

**If you find yourself:**
- Reading more than 10 files for a single task
- Using Glob with `**/*` without file type filtering
- Reading entire large files (>1000 lines) without specific need
- Re-reading files already examined in the conversation
- Exploring code "just to understand better" without clear need

**Then:** Stop and refine your approach. Ask yourself:
1. What specific information do I need?
2. What's the minimum search required to get it?
3. Can I infer this from what I already know?

## Integration with Other Skills

This skill should be applied in conjunction with:
- **code-quality.md**: Maintain quality while being efficient
- **testing.md**: Test only what's necessary, focus on critical paths
- **security.md**: Targeted security checks, not exhaustive scans
- **documentation.md**: Document changes, not entire codebase

## Success Metrics

**You're doing it right when:**
- Tasks complete in <20K tokens for most features
- You find what you need in 1-3 search operations
- You reference previous reads instead of re-reading
- You can justify every file you read
- Subagents return focused, relevant results

**Review and improve** if token usage is consistently high without proportional complexity in the task.