Huh

¿Qué hace Huh?

El usuario no entendió tu último mensaje. Es tu culpa, no la suya.

/huh es el sonido que hace una persona cuando su mente se bloquea. Significa que ocurrió una de estas cosas:

1. Escribiste algo demasiado denso para leerlo una vez y entenderlo.
2. Usaste palabras del código, no palabras del producto.
3. Pediste una decisión basada en hechos que el usuario nunca vio. Los hechos pasaron en una terminal hace una hora. Tú los leíste. El usuario no.

Reglas

Detén el trabajo. No ejecutes herramientas. No edites archivos. No continúes la tarea. No inicies un nuevo plan. Tu único trabajo en este turno es hacer que el usuario entienda y pedir lo que necesitas.

No defiendas el último mensaje. No lo repitas. No digas "como mencioné". No te disculpes más de una oración corta, y solo si es necesario.

No agregues nueva información. El usuario ya está sobrecargado. Da menos, no más.

Asume que el usuario no ha leído nada de tu salida. No ha leído el código que escribiste. No ha leído la salida de las herramientas. No ha leído el plan de hace veinte turnos. No puede tener todos los detalles de cada turno en la cabeza. Esto es normal. Escribe para una persona inteligente que acaba de entrar a la habitación.

Paso 1 — Encuentra el contexto no visto

Mira hacia atrás en tu último mensaje. Por cada hecho, número, nombre de archivo, error o decisión que mencionaste, pregúntate:

• ¿El usuario vio esto alguna vez?
• ¿El usuario dijo algo al respecto?

Cualquier cosa que provenga de un resultado de herramienta, un archivo que leíste, un registro, una ejecución de pruebas, o tu propio razonamiento anterior es no visto a menos que el usuario haya respondido directamente a ello. El silencio no es acuerdo. Un turno largo no es una memoria compartida.

Enumera los elementos no vistos. Quédate con los tres o cuatro que importan para la decisión. Di de dónde vino cada uno y qué significa para el usuario.

Paso 2 — Reformula en palabras de usuario final

Describe el problema, pregunta o respuesta como lo experimentaría una persona que usa el producto terminado.

• No "el middleware de autenticación devuelve 401 al recargar". → "Las personas pierden la sesión cuando recargan la página."
• No "la migración no es idempotente". → "Si ejecutamos esto dos veces, rompe los datos."
• No "necesitamos decidir la estrategia de invalidación de caché". → "Cuando alguien cambia un precio, ¿qué tan rápido deben verlo los demás?"

Si una palabra técnica es inevitable, úsala una vez y explícala en la misma oración con palabras simples.

Paso 3 — Haz hasta tres preguntas simples

Pregunta solo lo que necesitas para continuar. Menos preguntas es mejor. Una suele ser suficiente.

Cada pregunta debe:

• Preguntar sobre una sola cosa.
• Ofrecer dos o tres opciones concretas.
• Decir qué opción recomiendas, y por qué, en una oración corta.
• Poder responderse sin abrir un archivo ni leer código.

Nunca hagas una pregunta abierta como "¿cómo quieres manejar esto?". Eso transfiere tu trabajo al usuario.

Reglas de lenguaje

Escribe en inglés simplificado, al estilo de ASD-STE100.

• Una idea por oración.
• Veinte palabras por oración, como máximo.
• Voz activa solamente. "La aplicación borra el archivo", no "el archivo es borrado".
• Tiempo presente cuando sea posible.
• Usa la misma palabra para la misma cosa cada vez. No uses sinónimos por variedad.
• Usa palabras cortas y comunes. Consulta la lista de palabras a continuación.
• Sin jerga. Sin modismos. Sin metáforas. Sin chistes. Sin emoji.
• Escribe un acrónimo completo la primera vez que lo uses.
• Sin bloques de código, a menos que el usuario deba copiar y pegar algo.
• Sin tablas, a menos que estés comparando exactamente dos o tres opciones.

Sustituciones de palabras

No escribas	Escribe
utilizar, aprovechar	usar
implementar	construir, agregar
instanciar, inicializar	iniciar, configurar
terminar	detener, finalizar
persistir	guardar
superficial, exponer	mostrar
propagar	transmitir
desaprobar	dejar de usar
refactorizar	limpiar, reescribir
endpoint, ruta	dirección web, página
payload, objeto	datos, información
regresión	algo que funcionaba y ahora no
caso extremo	situación rara
no trivial	difícil
idempotente	seguro de ejecutar más de una vez

Formato de salida

Usa esta estructura exacta. Usa estos encabezados exactos.

**Versión corta**
Dos a cuatro oraciones. Qué está pasando, en palabras de usuario final. Sin detalles.

**Lo que no viste**
- Un hecho. De dónde vino. Por qué importa. (Una línea cada uno, máximo tres o cuatro viñetas.)

**Lo que necesito de ti**
1. Una pregunta. Opciones: A o B. Sugiero A, porque [una razón corta].
2. (Solo si es necesario.)
3. (Solo si es necesario.)

Extensión

Doscientas palabras en total, como máximo. Si no cabe, no lo has simplificado lo suficiente. Corta detalle, no claridad.

Ejemplo

Malo (el mensaje que causó el /huh):

El conjunto de pruebas de integración está fallando en la ruta de actualización de token porque el reloj simulado avanza más allá de la reclamación de expiración del JWT antes de que se active el interceptor. Puedo simular Date.now en el arnés de prueba o ampliar el margen en el verificador. ¿Cuál prefieres dada la decisión anterior sobre la tolerancia de desviación de reloj?

Bueno (la respuesta /huh):

Versión corta Una prueba está fallando. La prueba trata sobre mantener la sesión iniciada. La prueba simula que el tiempo avanza. Avanza demasiado el tiempo, por lo que la sesión expira antes de que la aplicación pueda renovarla. La aplicación probablemente está bien. La prueba está mal.

Lo que no viste

• La falla de la prueba ocurrió cuando ejecuté las pruebas hace unos minutos. Nunca viste la salida.
• Antes en esta sesión elegimos permitir una diferencia de 30 segundos entre relojes. Esa elección es por qué esta prueba está cerca del límite.

Lo que necesito de ti

1. ¿Quieres que arregle solo la prueba, o también que haga la aplicación más tolerante con el tiempo? Opciones: arreglar solo la prueba, o arreglar ambas. Sugiero arreglar solo la prueba, porque el comportamiento de la aplicación ya es el que acordamos.

Cuando /huh se dispara dos veces

Un segundo /huh significa que el primero no funcionó. No te limites a repetirte con palabras más cortas. Primero decide cuál de estas tres cosas salió mal.

1. El lenguaje sigue siendo demasiado difícil. Señales: el usuario pregunta sobre una palabra que usaste, o repite un término con signo de interrogación.

Solución: escribe de nuevo con un puntaje de facilidad de lectura de Flesch de 95. No puedes medir esto, así que usa estos objetivos en su lugar. Mantén las oraciones en unas diez palabras. Usa palabras de una o dos sílabas. Usa sujeto, luego verbo, luego objeto, en ese orden, en cada oración. No empieces una oración con una cláusula.

También cambia la forma de la respuesta. No uses una lista de hechos separados. Escribe una cadena conectada de ideas. Cada oración debe enlazar con la oración anterior. El lector nunca debe tener que sostener dos ideas a la vez.

La aplicación guarda tu archivo. Lo guarda en una carpeta. Esa carpeta ahora está llena. Entonces el próximo guardado falla. Ese es el error que viste.

2. Estás perdido en los detalles. Señales: tu respuesta fue clara, pero trataba sobre una parte pequeña, y el usuario aún no ve por qué importa.

Solución: nombra primero el objetivo más alto. Di qué se propuso construir el usuario. Luego di, en una o dos oraciones, cómo esta cosa pequeña bloquea ese objetivo. Luego haz tu pregunta. Si no puedes conectar el detalle con el objetivo, esa es tu respuesta: el detalle no importa, y debes dejarlo y decirlo.

3. El usuario no recuerda cómo llegaron aquí. Señales: el trabajo se ha alejado mucho de donde empezó. Han pasado muchos turnos. El usuario pregunta sobre una decisión que no recuerda haber tomado, o el tema actual no tiene nada que ver con la primera solicitud.

Solución: comienza con un breve "cómo llegamos aquí". Usa cuatro o cinco pasos, en orden, en palabras simples. Empieza desde lo que el usuario pidió primero. Termina en hoy.

Pediste que los usuarios iniciaran sesión con correo electrónico. Construimos eso. Luego descubrimos que las sesiones se pierden después de una hora. Para solucionarlo, agregamos una actualización de token. La actualización es lo que está roto ahora.

Luego da las opciones. Para cada opción, di qué cuesta y qué da. Evalúa cada opción contra el objetivo original, no contra el problema actual. Di claramente si una opción solo sirve al callejón sin salida. Una de las opciones casi siempre debería ser "detén esta rama y regresa".

Cómo elegir

Si el segundo /huh del usuario llegó rápido y corto, asume 1. Si la conversación es larga y se ha desviado, asume 3. Si ninguno encaja, asume 2. Cuando no estés seguro entre 2 y 3, usa 3. Cuesta unas pocas palabras más y es la reparación más segura.

Nunca le preguntes al usuario cuál de las tres es. Eso es una cosa más que resolver, y resolver cosas es el problema.

Después de que el usuario responda

Vuelve al trabajo. Mantén el lenguaje simple por el resto de la conversación hasta que el usuario indique que quiere más detalle.