telo3-ai 5.0.7 → 6.2.0

package/references/token-optimization.md

@@ -1,481 +1,114 @@
-# Token Optimization & Efficiency
+# Token Optimization
+**Load when:** diagnosing context bloat, inefficient reads, or interpreting token-loading estimates.
 
-> Smart AI behavior for minimal token usage and maximum effectiveness.
+Do what's needed. Skip what's not. Communicate concisely. Fewer tokens, same quality — measure, don't assume.
 
----
+## Two-Layer Architecture
 
-## Core Principle
+| Layer | What | When loaded | Cost |
+|---|---|---|---|
+| Core + host bridges | One compact core in AGENTS.md, tiny pointers in other host files; installed by chat file tools or activate | Host loads at session start/resume | Character-estimated core budget: 320 tokens for tested paths; long paths can add overhead |
+| Skill + references | Full SKILL.md and reference docs | On demand, per task, via the map below | Only what the task needs |
 
-**Do what's needed. Skip what's not. Communicate concisely.**
+`telo3 deactivate` removes the bootstrap block. Keep the bootstrap lean; push detail into on-demand references.
 
----
+## CLI
 
-## Token-Saving Rules
+| Command | Purpose |
+|---|---|
+| `telo3 install [dir] [--agent <host>]` | Copy a durable, discoverable project skill; no cache dependency |
+| `telo3 init [dir] [--context-dir <name>]` | Scaffold the six context documents |
+| `telo3 validate [dir] [--json] [--strict]` | Check required sections/structure |
+| `telo3 status [dir]` | Show context-system state |
+| `telo3 context <task> [dir] [--measure]` | Select task-relevant docs; `--measure` reports token counts |
+| `telo3 activate [dir]` | Install the bootstrap block into instruction files |
+| `telo3 deactivate [dir]` | Remove the bootstrap block |
+| `telo3 version` | Print CLI version |
 
-### 1. Read Selectively
+`context <task> --measure` estimates tokens as ceil(characters / 4). Compare selective docs + required refs with ALL six docs + those SAME refs. It measures input length, not actual model/API usage; do not call estimates observed token savings. Missing selected context is reported and detected secrets are redacted.
 
-❌ **DON'T:**
-- Read entire codebase
-- Read all context documents every time
-- Re-read files already in conversation
+## Selective Loading Map (memory.md always first)
 
-✅ **DO:**
-- Read only affected files
-- Check memory.md first (recent context)
-- Use grep to find relevant code
-- Read specific line ranges
+| Task | Context docs | Extra references (references/<name>.md) |
+|---|---|---|
+| feature | memory, prd, architecture, rules | — |
+| bugfix | memory, architecture, rules | — |
+| design | memory, design, rules | ui-quality |
+| security | memory, architecture, rules | security-quality, privacy-compliance |
+| privacy | memory, architecture | privacy-compliance, legal-compliance |
+| legal | memory, prd | legal-compliance |
+| accessibility | memory, design | accessibility-quality |
+| seo | memory, design | seo-quality, performance-quality |
+| performance | memory, architecture | performance-quality |
+| docs | memory | document-specification |
+| audit | all six | project-audit |
+| all | all six | — |
+| default/unknown | memory only | — |
 
-**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.
+## Reading Discipline
 
-Changed:
-- /api/users/search.ts (new)
-- components/UserSearch.tsx (new)
+- Don't re-read unchanged files already in context.
+- Read only affected code: files you will modify + their imports/dependencies.
+- Skip unrelated files: other features, tests (unless testing), config (unless changing it), docs (unless updating them).
+- Locate with grep/file search; read specific line ranges instead of whole files when only one function is needed.
+- Skim structure first; deep-read only relevant sections.
 
-Updated:
-- tasks.md (marked complete)
-- memory.md (added search feature)
+## Verification (corrected rule)
 
-Tested: Manual check. Works.
-```
+Verifying changed behavior before claiming done is REQUIRED — run/execute the change, check edge cases and related-feature regressions. What you skip is re-verifying unrelated, unchanged code.
 
-### Bug Fix
-```
-Fixed login redirect.
+| Situation | Verification |
+|---|---|
+| Any behavior change | Verify the change before claiming done |
+| Bug fix | Reproduce → fix → verify fix + no regressions |
+| Critical code (auth, payments, security) | Thorough checks; run relevant tests |
+| User requests tests, or a failure is mentioned | Run the relevant suite |
+| Trivial change (typo, comment, styling) | Quick check of the change itself; no full suite |
+| Unchanged, unrelated code | Skip — trust existing working code |
 
-Issue: Missing return statement
-Changed: auth.ts line 45
-Verified: Redirect works now
-```
+## Task Size
 
----
+| Size | Read | Plan | Verify | Update | Response |
+|---|---|---|---|---|---|
+| Tiny (1 file, obvious) | Affected file | None | The change | memory.md | 2–3 sentences |
+| Small/medium (few files) | memory + relevant doc + affected files | Brief outline | Change + critical paths | memory + tasks (+ changed docs) | Brief structured summary |
+| Large/complex | Context subset per map + affected code | Scoped plan; clarify missing consequential decisions | Relevant critical paths | Affected docs only | Result + evidence + gap |
 
-## Intelligent Tool Selection
+## Communication Contract
 
-### 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
-```
+Concise by default: result → changes → verification. No filler, no restating the request, no narrating tool calls, no excessive apologies or flowery language, no long explanations of obvious things.
 
-### 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.
-```
+Default report:
 
-**Good (Concise):**
 ```
-Auth feature complete.
-- Added login/signup
-- Error handling included
-- Docs updated
+Login redirect fixed.
+Changed: auth.ts (null check).
+Verified: login + redirect executed; works.
+Docs: memory.md, tasks.md 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
+Spend tokens on: relevant code, clear concise updates, decisions/tradeoffs, error explanations, security/privacy considerations, clarification when truly unclear.
 
----
+### Caveman Mode (opt-in only)
 
-## Efficiency Metrics (Self-Check)
+Enable only when the user asks for ultra-concise output ("caveman mode", "be concise", "token optimize"). Never force it. Then: short sentences, no filler, facts only, action → result → done ("Done. Tested. Works."). Return to normal when the user asks.
 
-After each task, mentally verify:
+## Tool Selection
 
-- [ ] 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?
+Tiny change → read exact file. Pattern/similar code → grep. Unknown location → file search. Single edit → string replace; related edits → multiple edits; full rewrite → write file.
 
-**Goal: 80% fewer tokens for same quality output**
+## Pattern Shortcuts
 
----
+| Request | Flow |
+|---|---|
+| Fix typo | Read file → fix → check change → done |
+| Update button color | design.md → update → verify rendering |
+| Add form field | Read form → add with validation → verify |
+| Fix bug | Read → fix → verify → memory.md |
+| Refactor | Read → plan → confirm with user → refactor incrementally, verifying |
 
-## 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.
-```
+## Self-Check
 
-**All subsequent responses:** Ultra-brief, action-focused, fact-only.
+- Read only necessary files? Skipped redundant (not required) verification?
+- Response short unless complex? Only changed docs updated? No redundant explanations?
+- Estimate context-loading cost with `telo3 context <task> --measure`; report actual API usage only if the host exposes it.