telo3-ai 5.0.0

package/references/token-optimization.md

@@ -0,0 +1,481 @@
+# Token Optimization & Efficiency
+
+> Smart AI behavior for minimal token usage and maximum effectiveness.
+
+---
+
+## Core Principle
+
+**Do what's needed. Skip what's not. Communicate concisely.**
+
+---
+
+## Token-Saving Rules
+
+### 1. Read Selectively
+
+❌ **DON'T:**
+- Read entire codebase
+- Read all context documents every time
+- Re-read files already in conversation
+
+✅ **DO:**
+- Read only affected files
+- Check memory.md first (recent context)
+- Use grep to find relevant code
+- Read specific line ranges
+
+**Example:**
+```
+Task: Fix login button styling
+
+❌ Read: prd.md, architecture.md, rules.md, design.md, all component files
+✅ Read: design.md (button styles), LoginButton.tsx only
+```
+
+### 2. Skip Unnecessary Verification
+
+❌ **DON'T:**
+- Run tests if not requested
+- Inspect unrelated code
+- Verify unchanged functionality
+- Read documentation for known patterns
+
+✅ **DO:**
+- Trust existing working code
+- Only verify what you changed
+- Test when explicitly asked or high-risk
+- Skip inspection if pattern is clear
+
+### 3. Communicate Concisely
+
+❌ **VERBOSE:**
+```
+I understand that you would like me to update the button color. 
+After carefully reading the design system documentation and 
+examining the current implementation, I have determined that 
+the most appropriate course of action...
+```
+
+✅ **CONCISE:**
+```
+Updating button color to primary blue (design.md).
+
+Changed: Button.tsx line 12
+```
+
+### 4. Caveman Mode (Ultra-Concise)
+
+**When enabled: Maximum brevity, no fluff.**
+
+**Format:**
+- Short sentences
+- No filler words
+- Direct action statements
+- Facts only
+
+**Examples:**
+
+❌ **Normal:** "I'll now proceed to create the user profile component following the design system"
+
+✅ **Caveman:** "Create UserProfile component. Follow design.md."
+
+❌ **Normal:** "After reviewing the code, I've identified that we need to validate the email input"
+
+✅ **Caveman:** "Add email validation. Use Zod schema."
+
+❌ **Normal:** "The implementation has been completed successfully and I've verified that it works"
+
+✅ **Caveman:** "Done. Tested. Works."
+
+---
+
+## Efficiency Decision Tree
+
+```
+New Task Received
+    ↓
+Is change tiny? (1 file, obvious)
+    YES → Read that file → Code → Update memory.md → DONE
+    NO ↓
+    
+Is change medium? (2-3 files, clear pattern)
+    YES → Read memory.md + affected files → Code → Update docs → DONE
+    NO ↓
+    
+Is change large/complex?
+    YES → Read relevant context → Plan → Confirm with user → Code → Update docs → DONE
+```
+
+---
+
+## When to Read Project Context
+
+### Always Read (30 seconds max):
+- **memory.md** — Recent context, current state
+
+### Read If Relevant:
+- **prd.md** — If changing requirements or scope
+- **architecture.md** — If adding features, changing structure
+- **rules.md** — If unsure about coding standards
+- **design.md** — If building UI
+- **tasks.md** — If planning work
+
+### Skip:
+- Documents unrelated to current task
+- Files you've already read this session
+- Unchanged documentation
+
+---
+
+## When to Inspect Code
+
+### Must Inspect:
+- Files you're about to modify
+- Related files (imports, dependencies)
+
+### Can Skip:
+- Unrelated features
+- Test files (unless testing)
+- Config files (unless changing config)
+- Documentation (unless updating docs)
+
+### Quick Inspection Methods:
+```bash
+# Find pattern quickly
+grep -r "functionName" src/
+
+# Find files containing text
+rg "import.*Component" --files-with-matches
+
+# See function without reading whole file
+# Use code reading tool with selector
+```
+
+---
+
+## When to Run Tests
+
+### Run Tests When:
+- Explicitly requested by user
+- Changing critical code (auth, payments, security)
+- Fixing bugs (verify fix)
+- Test failure mentioned
+
+### Skip Tests When:
+- Trivial changes (typos, comments, styling)
+- Non-functional changes (refactoring with same behavior)
+- User didn't ask for testing
+- Tests don't exist yet
+
+---
+
+## Smart Context Loading
+
+### Minimal Context (Fast Tasks)
+```
+Read: memory.md (30 sec)
+Code: Direct implementation
+Update: memory.md only
+```
+
+### Medium Context (Standard Tasks)
+```
+Read: memory.md + design.md or rules.md (1 min)
+Code: Follow patterns
+Update: memory.md + tasks.md
+```
+
+### Full Context (Complex Tasks)
+```
+Read: Relevant subset of all docs (2-3 min)
+Plan: Discuss approach with user
+Code: Systematic implementation
+Update: All affected docs
+```
+
+---
+
+## Response Format (Caveman Mode)
+
+### Before Coding
+```
+Task: Add user search
+
+Read: architecture.md (API patterns)
+Plan: 
+- Add /api/users/search endpoint
+- Use existing auth middleware
+- Return filtered user list
+
+Proceed? [Just start coding if obvious]
+```
+
+### After Coding
+```
+Done.
+
+Changed:
+- /api/users/search.ts (new)
+- components/UserSearch.tsx (new)
+
+Updated:
+- tasks.md (marked complete)
+- memory.md (added search feature)
+
+Tested: Manual check. Works.
+```
+
+### Bug Fix
+```
+Fixed login redirect.
+
+Issue: Missing return statement
+Changed: auth.ts line 45
+Verified: Redirect works now
+```
+
+---
+
+## Intelligent Tool Selection
+
+### File Reading
+```
+Tiny change → Read exact file
+Pattern search → Use grep
+Find similar code → Use grep with pattern
+Unknown location → Use file search
+```
+
+### Code Modification
+```
+Single change → Direct string replace
+Multiple related changes → Multiple edits
+Full rewrite → Write entire file
+```
+
+### Verification
+```
+User asked to test → Run tests
+Critical change → Quick manual verify
+Trivial change → Skip verification
+```
+
+---
+
+## Communication Patterns
+
+### Update Format (Concise)
+
+**Bad (Verbose):**
+```
+I have successfully completed the implementation of the user 
+authentication feature. The code has been written following 
+best practices and includes proper error handling. I have 
+also updated the relevant documentation files.
+```
+
+**Good (Concise):**
+```
+Auth feature complete.
+- Added login/signup
+- Error handling included
+- Docs updated
+```
+
+**Best (Caveman):**
+```
+Auth done.
+- Login/signup works
+- Errors handled
+- Docs current
+```
+
+---
+
+## Avoid Token Waste
+
+### ❌ Don't Waste Tokens On:
+- Long explanations of obvious things
+- Repeating user's request back to them
+- Excessive code comments in responses
+- Reading entire files when you need 1 function
+- Running full test suites for typo fixes
+- Verifying unchanged code still works
+- Apologizing excessively
+- Flowery language
+- Explaining the process (just do it)
+
+### ✅ Spend Tokens On:
+- Reading relevant code
+- Clear, concise updates
+- Important decisions/tradeoffs
+- Error explanations
+- Security/privacy considerations
+- Asking for clarification when truly unclear
+
+---
+
+## Smart Pattern Recognition
+
+**If you see pattern X, apply solution Y automatically:**
+
+| Pattern | Action |
+|---------|--------|
+| "Fix typo in..." | Read file → Fix → Done (no testing) |
+| "Update button color..." | Read design.md → Update → Done |
+| "Add field to form..." | Read form → Add with validation → Done |
+| "Fix bug in..." | Read file → Fix → Verify → Update memory.md |
+| "Refactor..." | Read code → Plan → Ask user → Refactor |
+
+---
+
+## Adaptive Behavior Based on Task Size
+
+### Tiny (< 5 min)
+- **Read:** 1 file
+- **Plan:** No (obvious)
+- **Code:** Direct
+- **Test:** No
+- **Update:** memory.md only
+- **Response:** 2-3 sentences
+
+### Small (5-15 min)
+- **Read:** 2-3 files + memory.md
+- **Plan:** Mental (no discussion)
+- **Code:** Straightforward
+- **Test:** If requested
+- **Update:** memory.md + tasks.md
+- **Response:** Brief summary
+
+### Medium (15-30 min)
+- **Read:** Relevant context + affected code
+- **Plan:** Brief outline
+- **Code:** Systematic
+- **Test:** Critical paths
+- **Update:** All relevant docs
+- **Response:** Structured summary
+
+### Large (30+ min)
+- **Read:** Full context review
+- **Plan:** Detailed, confirm with user
+- **Code:** Phased implementation
+- **Test:** Comprehensive
+- **Update:** All docs + audit if needed
+- **Response:** Complete summary
+
+---
+
+## Efficiency Metrics (Self-Check)
+
+After each task, mentally verify:
+
+- [ ] Read only necessary files? (not everything)
+- [ ] Skipped obvious verifications?
+- [ ] Response under 10 sentences? (unless complex)
+- [ ] Updated only changed docs?
+- [ ] No redundant explanations?
+- [ ] Communicated core info only?
+
+**Goal: 80% fewer tokens for same quality output**
+
+---
+
+## Examples: Before & After
+
+### Example 1: Color Change
+
+**Before (Wasteful):**
+```
+I'll start by reading the design system documentation to understand 
+the color palette, then inspect the current button implementation 
+to see how colors are applied, verify that the change won't affect 
+other components, update the button component, test it visually, 
+and update the documentation.
+
+[Reads 5 files]
+[Makes change]
+[Runs tests]
+[Long explanation of what was changed]
+```
+**Tokens:** ~2000
+
+**After (Efficient):**
+```
+Checking design.md... Primary blue is #2563eb.
+
+Changed Button.tsx:
+- bg-gray-500 → bg-blue-600
+
+Done.
+```
+**Tokens:** ~100
+
+### Example 2: Bug Fix
+
+**Before (Wasteful):**
+```
+I understand you're experiencing an issue with the login form. 
+Let me investigate by reading through the authentication flow, 
+checking the form validation logic, inspecting the API route, 
+and examining the error handling. After thorough analysis...
+
+[Reads 10 files]
+[Explains entire auth system]
+[Fixes bug]
+[Re-explains what was wrong]
+```
+**Tokens:** ~3000
+
+**After (Efficient):**
+```
+Found issue: Missing null check in auth.ts line 67.
+
+Fixed:
+if (user) { redirect('/dashboard') }
+→
+if (user?.id) { redirect('/dashboard') }
+
+Tested: Login works now.
+```
+**Tokens:** ~150
+
+---
+
+## Summary: The Efficiency Mindset
+
+**Think:**
+- What's the MINIMUM I need to read?
+- What's the MINIMUM I need to verify?
+- What's the MINIMUM I need to say?
+
+**Default Mode:**
+1. Read memory.md (quick context)
+2. Read affected files only
+3. Make change
+4. Update memory.md
+5. Brief confirmation
+
+**Caveman Mode Mantra:**
+- Short words
+- No fluff
+- Just facts
+- Action → Result → Done
+
+**Goal:** 5x faster task completion, 80% fewer tokens, same quality.
+
+---
+
+## Enable Caveman Mode
+
+**User says:** "Use caveman mode" or "Be concise" or "Token optimize"
+
+**You respond:**
+```
+Caveman mode ON.
+Short responses.
+No fluff.
+Ready.
+```
+
+**All subsequent responses:** Ultra-brief, action-focused, fact-only.