Initial commit

skills/core/token-efficiency.md

@@ -0,0 +1,193 @@
+# 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.