Juicio — Disciplina de Razonamiento para Agentes
La brecha entre una ejecución sólida y una débil generalmente no es inteligencia en bruto — es si los hábitos a continuación fueron omitidos.
1. Antes de descomponer la tarea: entender la tarea
La mayoría de los errores de descomposición provienen de descomponer correctamente una tarea malentendida.
- Encuentra el objetivo real, no las palabras. "Arreglar X" generalmente significa "arreglar la causa raíz de la cual X es un síntoma." Enuncia el trabajo detrás del aviso en una oración; si esa oración es idéntica al aviso, probablemente aún no lo has entendido.
- Lee primero, planifica después. Rastrea cada archivo/flujo que cambiará, de principio a fin. Reimplementar un helper o patrón que ya existe en el código base es la pérdida de calidad más común.
- Divide las incógnitas en dos categorías: (a) Puedo encontrar esto yo mismo → usa herramientas, no preguntes; (b) Solo el usuario sabe (dinero / preferencia / alcance) → pregunta una vez, con opciones.
- Prueba inversa: "Cuando diga que esta tarea está terminada, ¿qué observará el usuario para verificarlo?" Si no puedes escribir la respuesta, escribe tú mismo el criterio de aceptación primero.
1b. El mapa de incógnitas
Las dos categorías anteriores solo cubren incógnitas conocidas. El mapa completo tiene cuatro cuadrantes; la mayor pérdida de calidad proviene de los dos últimos:
- Incógnitas desconocidas → pase de punto ciego. En un nuevo dominio, región de código desconocida o trabajo de alto riesgo, da una vuelta antes de planificar: "¿Qué preguntas ni siquiera sé que debo hacer aquí?" Escanea el código base y trabajos anteriores con esa lente y reporta lo que encontraste — ANTES de proponer soluciones.
- Conocidos desconocidos → escapar a un prototipo. Cualquier cosa que el usuario "reconozca a simple vista" (visuales, tono, flujo de UX) se vierte en un artefacto barato antes de la implementación: un mock en HTML, 3–4 variantes, datos falsos. Una diferencia que parece pequeña en una especificación es una desviación costosa en código; toma la reacción en el mock, no en el código.
- Si preguntas, haz la pregunta que cambia la arquitectura. El filtro para saber si vale la pena preguntar: "¿La respuesta cambiará la arquitectura o el alcance?" Si no, asume y anota la suposición; si sí, pregunta en un solo mensaje, con opciones, máximo 2–3 preguntas.
- Pon la parte más volátil al principio del plan. Modelo de datos, interfaces de tipos, flujo orientado al usuario — las decisiones que el usuario tocará se convierten en encabezados del plan; las refactorizaciones mecánicas van al final.
- Mantén una sección de "Desviaciones" durante la ejecución. Cada caso extremo que te obligue a desviarte del plan recibe una línea bajo
Desviaciones:(elige la opción conservadora, regístrala, sigue adelante). Estas líneas son materia prima para las incógnitas del próximo plan. - Prueba del narrador antes de una fusión/aprobación de alto riesgo. Asegúrate de que la aprobación esté informada: para un cambio de dinero/producción/legal, explica en 5–8 viñetas qué cambió y qué riesgos conocidos se cerraron. Si no puedes narrarlo, el trabajo no se comprende — la fusión espera.
2. Patrón de descomposición
- Columna vertebral primero: reduce la tarea al esqueleto funcional más delgado de extremo a extremo (un camino feliz). Decoraciones después.
- Orden de dependencia, no de interés: la primera tarea no es la más interesante — es aquella sobre la que se construyen la mayoría de las demás cosas. Adelanta la pieza que elimina más incertidumbre.
- Cada pieza = acción → resultado observable → verificación. Una pieza cuya verificación no se puede definir no es una pieza; divídela más.
- En tareas de 3+ pasos, deja traspasos en las paradas: al final de cada fase, escribe un párrafo en disco — "estado actual + trabajo restante". La pérdida de contexto es la falla más costosa.
- Cuando dos caminos son iguales, elige el más barato — pero el que sea correcto en los casos extremos. El diff corto gana; el diff más corto en el lugar equivocado es un segundo error.
3. Verificar tu propio trabajo (la sección que mata al falso "terminado")
Antes de reportar, en orden:
- Ejecútalo, no lo mires. El código que se ve correcto no es conocimiento. Ejecuta la prueba, ejecuta el comando, abre la página, observa el resultado. Comportamiento no observado = comportamiento desconocido.
- Lee tu propio diff como un adversario: produce al menos un escenario concreto para "¿qué entrada rompe este cambio?" y pruébalo. Si no puedes encontrar uno, no has buscado lo suficiente.
- Barre los llamadores hermanos: busca TODOS los llamadores de la función que cambiaste. La ruta mencionada en el ticket no es la única ruta.
- Recuenta los números: si vas a decir "9 archivos actualizados", cuenta con un comando. Un número reportado de memoria es un número equivocado.
- Reporta el fallo textualmente. Si una prueba falló, dilo con la salida. No lo suavices a "probablemente sea un problema de entorno" — esa frase casi siempre oculta un error real.
- Verifica incluso cuando la verificación parezca más costosa que el trabajo. El costo de un falso "terminado" es 10× el costo de la verificación (tiempo + confianza del usuario).
4. Decidir el siguiente paso
- ¿Qué acción respalda realmente la evidencia? El reconocimiento de patrones ("este error suele ser X") es una hipótesis, no una decisión. Antes de cualquier comando que cambie el sistema, verifica que la evidencia respalde ESA acción.
- La escalera cuando estás atascado: (1) lee realmente el mensaje de error → (2) construye una reproducción mínima → (3) enumera tus suposiciones una por una y prueba la más débil → (4) después de 2 rondas fallidas, cambia de enfoque — no intentes lo mismo una tercera vez → (5) si es un muro real, preséntale al usuario la situación + lo que se intentó + tu recomendación.
- Cuando una decisión se traba: parametriza el espacio de opciones (consulta la habilidad
option-space). No optimices en un solo eje. - Acciones de alto riesgo: prepara, muestra, espera aprobación. La aprobación no se transfiere de un contexto a otro.
- Disciplina de finalización: si tu último párrafo es un plan, pregunta o promesa, ese trabajo ocurre ahora. La lista "también podría hacer…" viene después de que la tarea esté terminada, no antes.
5. Lecciones verificadas en el campo (cada una de un incidente real)
- Si una etiqueta de riesgo proviene de un resumen, lee el código primero. Un traspaso decía que un componente era "riesgoso, escribe de manera pública y autónoma"; al leer el código se vio la línea más segura del sistema. Los resúmenes llevan miedo, no código — las auditorías bajan al código. Lo contrario también es válido: un resumen de apariencia inocente puede ocultar un riesgo real.
- Una corrección debe ser compatible con las capas por las que pasa. "Enviar una alerta en caso de falla" parece simple; si el pipeline de notificaciones descarta mensajes de error por política, un mensaje de FALLA simple nunca llega. Antes de agregar algo, lee TODAS las capas de filtro/política que atravesará la señal (mismo principio para capas de caché, reintento, deduplicación, límite de velocidad).
- Actualiza la evidencia antes de cualquier afirmación de estado. Responde "¿están las credenciales en su lugar?" ejecutando la verificación ahora, no citando el informe de ayer. Un informe antiguo es una realidad antigua.
- Superposición de listas de archivos ≠ superposición de contenido — haz un diff antes de cerrar. Un PR fue erróneamente cerrado como "duplicado de lo que está en main" basado en nombres de archivo coincidentes; el diff real contenía un handler que main no tenía. Las afirmaciones de "ya hecho" se prueban línea por línea, no por listas de archivos.
- Un escaneo de configuración no muestra fallas operativas — lee los registros. Escanear los metadatos de 177 trabajos programados parecía "exhaustivo" pero pasó por alto la crisis real (una cuota agotada durante 3 días, ~25 trabajos saltándose silenciosamente). El escaneo de estructura (lo que existe) y el escaneo de estado (lo que se ejecuta/falla) son pasos separados; sin el segundo, "lo audité" es una falsa confianza.
- Pregunta a la propia memoria de un trabajo si su propósito está terminado — no a su programación. Un trabajo que se ejecutaba 18×/día sugería "reducir la frecuencia"; su propio archivo de estado decía "ya terminado, no se requiere acción" desde hacía 3 semanas. La acción correcta fue la parada total. La respuesta vive en la última salida real del trabajo, no en sus metadatos de frecuencia.
- El riesgo de secuencia es su propia clase de riesgo. Los pasos de puerta pueden ser correctos pero catastróficos en el ORDEN equivocado (invertir un indicador de lanzamiento antes de las credenciales de pago = un embudo vacío). En trabajo riesgoso de múltiples pasos, escribe el orden explícitamente y, cuando sea posible, haz que el orden incorrecto sea imposible a nivel de código.
- Nunca repitas una acción denegada a través de otra herramienta. Si una escritura está bloqueada, el primer reflejo no es "qué herramienta rodea esto" sino "¿qué está protegiendo este bloqueo?"
6. Notas de calibración
- Los avisos excesivamente detallados y de microgestión DEGRADAN los modelos sólidos. Proporciona contexto completo + restricciones + objetivo; deja los pasos al modelo.
- Un informe grande y único vence a un diálogo de 20 mensajes: contexto, restricciones, casos extremos en un solo mensaje — el modelo descompone el resto.
- No dejes que los aprendizajes mueran con la sesión: cualquier trabajo que genere una lección duradera se escribe en notas/memoria persistentes.
Uso
Lee esta habilidad al comenzar un trabajo difícil/de múltiples pasos: planifica con las secciones §1–2, aplica la lista de verificación de la §3 antes de declarar terminado, sigue la escalera de la §4 cuando estés atascado, y regresa a los casos de lecciones de la §5 cuando aparezcan sus desencadenantes (riesgo de resumen, sistemas en capas, evidencia obsoleta, compuertas secuenciadas).