token-efficiency-rules.md

# Token Efficiency Rules - Operational Spec

> Reglas operacionales para Fred al trabajar con Alex. Optimizar uso de tokens sin sacrificar calidad.

## Objetivo
Completar tareas con mínimo contexto necesario, mínimas tool calls innecesarias, máxima verificación.

---

## Reglas Primarias

1. **Search Before Read** - SIEMPRE usar Grep/Glob para localizar ANTES de Read
2. **Load Only Necessary** - No leer archivos completos para encontrar una función
3. **No Restate** - No repetir información conocida
4. **No Decorative Prose** - Sin "Excelente pregunta!", sin conversación de relleno
5. **Targeted Retrieval** - Específico > exploratorio
6. **Summaries Over Dumps** - Resúmenes, diffs, line ranges > archivos completos
7. **Subagents for Noise** - Task tool con Explore agent para trabajo ruidoso
8. **Verify with Tools** - Tests, linters, comandos > explicaciones
9. **Clear Between Tasks** - No arrastrar contexto de tareas no relacionadas
10. **Read Credentials on Demand** - NUNCA cargar `credentials.md` sin necesidad

---

## File Reading Policy

### ❌ NUNCA hacer:
- Leer archivo completo para localizar una función/clase/error
- Leer múltiples archivos "por si acaso"
- Volcar logs completos de systemd/nginx

### ✅ SIEMPRE hacer:
```bash
# 1. Localizar primero
Grep "class UserAuth" *.py

# 2. Leer solo región necesaria
Read file.py (líneas 45-78)

# 3. Si es log, filtrar primero
journalctl -u prospector -p err -n 50
journalctl -u prospector | grep -E "(ERROR|Exception|Failed)" | tail -20
```

---

## Tool Use Policy

### Parallel cuando sea independiente:
```
# ✅ Bien (independientes)
Read file1.py
Read file2.py
Bash "git status"

# ❌ Mal (dependen secuencialmente)
Bash "mkdir dir && cp file dir"  # Usar && en un solo Bash
```

### Filtrar antes de mostrar:
```bash
# ❌ Mal
cat /var/log/nginx/error.log  # 10000 líneas

# ✅ Bien
tail -f /var/log/nginx/error.log | grep -v "robots.txt" | grep ERROR | tail -20
```

---

## Context Architecture

### CLAUDE.md
- **Target:** < 150 líneas
- **Contiene:** Solo esencial (identidad, idioma, preferencias, anti-patterns)
- **NO contiene:** Credenciales, tablas de servicios, detalles de proyectos

### MEMORY.md
- **Target:** < 180 líneas
- **Contiene:** Índice + referencias a archivos detallados
- **NO contiene:** Credenciales completas, tablas extensas

### Archivos de referencia (leer bajo demanda):
- `credentials.md` - Solo cuando se necesiten credenciales específicas
- `vps-services.md` - Solo cuando se trabaje con VPS
- `projects-local.md` - Solo cuando se trabaje con proyectos Desktop
- `vps-capabilities-index.md` - Routing de intenciones (CRÍTICO)
- Archivos específicos (nexuslex.md, transcrip-beepeek.md, etc.) - Solo cuando se mencionen

---

## Output Policy

### ✅ Preferir:
- Plan conciso
- Edit concreto
- Comando exacto
- Resultado verificación
- Resumen de estado corto

### ❌ Evitar:
- Repetir tarea del usuario
- "Voy a hacer X" antes de hacerlo (solo hacerlo)
- Explicaciones largas cuando un diff/comando es suficiente
- Conversación decorativa

### Ejemplo:

**❌ Mal:**
```
¡Excelente pregunta! Voy a ayudarte a revisar el servicio Prospector.
Primero voy a leer los logs para ver qué está pasando...
[Lee 1000 líneas de logs]
```

**✅ Bien:**
```
[Grep en logs por ERROR]
[Muestra solo líneas relevantes]
Error en línea 145: conexión Supabase timeout.
```

---

## Noisy Data Handling

### Logs
**NUNCA** volcar logs completos. Siempre filtrar primero:

```bash
# ❌ Mal
journalctl -u prospector -n 1000

# ✅ Bien
journalctl -u prospector -p err -n 50  # solo errores
journalctl -u prospector --since "5 minutes ago" | grep -E "(ERROR|WARN|Exception)"
```

### JSON/Payloads grandes
Si output > 100 líneas:
1. Escribir a archivo temporal
2. Analizar externamente
3. Devolver solo resumen + campos clave

---

## Subagents Strategy

### Usar Task tool con Explore agent para:
- Exploración de código nuevo/legacy
- Análisis de logs extensos
- Búsquedas amplias en codebase
- Investigación que requiera > 3 queries

### Resultado esperado:
- Solo hallazgos clave (< 50 líneas)
- NO contexto interno del agente
- Actúa como firewall de contexto

### Ejemplo:
```
# ❌ Mal
Read file1.py
Read file2.py
Read file3.py
Grep "UserAuth" *.py
Read file4.py
...

# ✅ Bien
Task tool (Explore): "Localizar implementación UserAuth en hub-beepeek"
[Agente devuelve: "Encontrado en apps/hub/auth.py líneas 45-89, usa JWT HS256"]
Read apps/hub/auth.py (líneas 45-89)
```

---

## VPS Workflow

### Antes de trabajar con VPS:
1. ¿Necesito credenciales? → Read `credentials.md` (solo sección necesaria)
2. ¿Necesito info de servicio? → Read `vps-services.md` (solo tabla relevante)
3. ¿Qué comando ejecutar? → Consultar `vps-capabilities-index.md` PRIMERO

### Debug de servicio:
```bash
# 1. Ver status
systemctl status <service>

# 2. Si falla, ver logs filtrados
journalctl -u <service> -p err -n 30

# 3. Si aún no hay info, ampliar búsqueda
journalctl -u <service> --since "10 minutes ago" | grep -E "(ERROR|Exception|Failed)"
```

---

## Credentials Strategy

### ✅ Cargar credentials.md solo cuando:
- Se necesita conectar FTP/SSH/API
- Se va a hacer deploy
- Error de autenticación específico

### ❌ NUNCA cargar credentials.md:
- Al inicio de sesión "por si acaso"
- Para tareas de lectura/exploración
- Cuando ya están en contexto reciente

### Técnica:
```
# ❌ Mal
Read credentials.md  # 200+ líneas cargadas

# ✅ Bien
Read credentials.md (líneas 45-52)  # Solo sección FTP Monte Rentals
```

---

## Anti-patterns (NUNCA hacer)

1. ❌ Leer archivos completos sin localizar primero
2. ❌ Volcar logs completos (> 50 líneas)
3. ❌ Cargar credentials.md sin necesidad específica
4. ❌ Exploración "a ciegas" (leer 10 archivos para entender proyecto)
5. ❌ Conversación decorativa ("Excelente pregunta!", "Vamos a...")
6. ❌ Repetir información ya conocida
7. ❌ Tool calls redundantes (3 Read cuando un Grep localiza)
8. ❌ Explicaciones largas cuando comando/diff es suficiente

---

## Default Workflow

1. Identificar tarea exacta
2. ¿Necesito credenciales? → Read `credentials.md` (solo sección)
3. ¿Necesito info VPS? → Read `vps-services.md` (solo tabla)
4. **Grep/Glob primero** para localizar
5. **Read solo región necesaria**
6. Hacer cambio mínimo válido
7. Verificar con tool determinístico (test, lint, bash check)
8. Resumen conciso de resultado

---

## Behavioral Summary

Operar como ingeniero disciplinado con máquina de memoria escasa:
- **Load less** - Solo lo necesario
- **Search first** - Grep antes de Read
- **Read narrowly** - Line ranges, no archivos completos
- **Isolate noise** - Subagents para exploración
- **Verify deterministically** - Tests/linters, no explicaciones
- **Summarize densely** - Conciso, sin decoración
- **Reset aggressively** - No arrastrar contexto entre tareas distintas

---

## Metrics de Éxito

### Session eficiente:
- < 10 tool calls para tarea simple
- < 3 Read por archivo (1 ideal)
- 0 volcados de logs completos
- credentials.md cargado solo cuando se usa
- Output directo, sin conversación

### Session ineficiente:
- > 20 tool calls para tarea simple
- Múltiples Read del mismo archivo
- Logs sin filtrar
- credentials.md cargado "por si acaso"
- Explicaciones largas antes de actuar