docs(methodology): commit inicial del método de trabajo con agentes

methodology/PRINCIPLES.md

@@ -0,0 +1,90 @@
+# Principios fundamentales
+
+> Los 5 principios que sostienen todo el método. Si tu equipo solo recuerda esto, ya tiene 80% del valor. Los patrones son aplicaciones derivadas.
+
+---
+
+## 1. La especificación precede al código
+
+Antes de pedirle a un agente que genere código, **la especificación tiene que estar escrita, versionada y validada**. No hay excepciones.
+
+**Por qué:** un agente sin especificación genera código que parece razonable pero no resuelve el problema que vos tenés. Termina rápido, queda mal, y descubrís el desfase 3 días después cuando es caro arreglarlo.
+
+**Cómo se aplica:** todo sprint arranca con un brief versionado en `sprints/sprint-N/BRIEF.md`. Todo cambio importante dentro de un sprint arranca con un mockup o ADR. Todo tarea agéntica arranca con un prompt en archivo, no improvisado en chat.
+
+**Cuándo NO aplica:** experimentación pura sin entregable. Si estás explorando si una librería sirve, podés hacer prompts libres. Pero el output de esa experimentación nunca va directo a producción.
+
+---
+
+## 2. La validación humana es ojo, no test
+
+Los tests verdes no equivalen a etapa terminada. **El humano abre el artefacto final con sus ojos antes de declarar completado.**
+
+**Por qué:** los agentes producen outputs que técnicamente cumplen los criterios programáticos pero pierden el contexto del producto. Tests verdes garantizan que el código no falla. Validación visual garantiza que el output es presentable.
+
+**Cómo se aplica:** si el output es un archivo visible (PDF, screenshot, página web, documento), el humano lo abre. Si el output es código, el humano lo lee al menos en diagonal. Si el output es comportamiento (un endpoint que responde algo), el humano lo ejecuta manualmente al menos una vez antes del merge.
+
+**Cuándo NO aplica:** outputs puramente internos (helpers, refactors estructurales) que se validan exclusivamente por tests. Pero estos casos son minoría.
+
+---
+
+## 3. La auditoría es adversarial, no confirmatoria
+
+Cuando revisás el output de un agente, **buscá lo que está mal**, no lo que está bien. Confirmar es fácil; el agente ya viene optimizado para producir cosas que parecen correctas. Tu valor está en detectar lo que el agente racionalizó.
+
+**Por qué:** los agentes tienen un sesgo hacia reportar éxito. "Tests verdes, build limpio, etapa completada" suena bien pero puede ocultar que el archivo generado no es el correcto, que la métrica no cuadra con los inputs, o que un detalle crítico se omitió silenciosamente.
+
+**Cómo se aplica:** cuando recibís un reporte de agente, hacé tres preguntas antes de aprobar:
+1. ¿Los números que reportó cuadran si los recalculo a mano o pido detalle?
+2. ¿El artefacto entregado es el que pedí o uno parecido?
+3. ¿Lo que no menciona el reporte podría ser relevante?
+
+**Cuándo NO aplica:** tareas rutinarias de bajo riesgo donde el costo de auditar supera el costo de un error. Pero estas son menos de las que parecen.
+
+---
+
+## 4. Las decisiones se registran como contratos
+
+Toda decisión arquitectónica, de marca, o de proceso se documenta en el lugar correcto **explícitamente**, no en la memoria de quien decidió. Cuando aparece de nuevo, no se re-debate.
+
+**Por qué:** las decisiones no registradas se erosionan. Un agente vuelve a preguntar lo mismo en la siguiente sesión, un miembro del equipo asume distinto, vos mismo en 2 semanas no recordás por qué eligieron X. El costo de re-debatir es alto y los outputs quedan inconsistentes.
+
+**Cómo se aplica:**
+- Decisiones de producto → `CLAUDE.md` (reglas no negociables) o `ARCHITECTURE.md` (ADRs)
+- Decisiones de método → `methodology/PATTERNS.md`
+- Decisiones de etapa → "DECISIONES YA TOMADAS" en el prompt de la siguiente etapa
+- Decisiones de marca → `DESIGN_SYSTEM.md` o `BRAND_GUIDE.md`
+
+**Cuándo NO aplica:** decisiones reversibles sin costo. Si elegís un nombre de variable, no lo documentes formalmente.
+
+---
+
+## 5. El humano es director, no operador
+
+Tu trabajo es decidir **qué** se hace, **cuándo** se valida, y **si** lo entregado es aceptable. NO es traducir entre el agente y el código. Si te encontrás ejecutando comandos que el agente podría ejecutar, parar y delegarlos.
+
+**Por qué:** el humano operador es el cuello de botella del sistema. Cada minuto que pasás copiando-pegando, formateando outputs, o transportando contexto entre sesiones, es un minuto que no estás pensando en producto, arquitectura, o estrategia. El humano vale por su criterio, no por su throughput.
+
+**Cómo se aplica:**
+- Si el prompt se puede pre-armar en archivo, hacelo. No lo tipees cada vez.
+- Si la validación se puede automatizar (test, lint, screenshot), automatizala.
+- Si la decisión es repetitiva (formato, nombre, paleta), documentala una vez y referenciala.
+- Si te volvés "pasamanos" entre dos agentes, frená y revisá el flujo.
+
+**Cuándo NO aplica:** las primeras 2-3 veces que aplicás el método, la operación manual es parte del aprendizaje. Después, la operación es señal de fricción que hay que eliminar.
+
+---
+
+## Cómo se relacionan los 5 principios
+
+```
+1. Especificación precede al código    →  evita falsos arranques
+2. Validación humana es ojo           →  evita falsos cierres
+3. Auditoría adversarial              →  evita aprobaciones engañosas
+4. Decisiones como contratos          →  evita re-debate y deriva
+5. Humano director, no operador       →  evita cuello de botella
+```
+
+Los principios 1-2 protegen las puntas (entrada y salida del trabajo).
+Los principios 3-4 protegen la mitad (cómo evaluamos y registramos).
+El principio 5 protege la sostenibilidad (que el método escale).