Estados de IA
Diseña los momentos de una función de IA además de aquel en el que funciona.
Los equipos diseñan la demo: el usuario pregunta, la IA responde, todos aplauden. Luego la gente real la usa. Preguntan algo que no puede hacer, tarda catorce segundos, responde con total seguridad y está equivocada, la conexión se cae a mitad de frase, y el producto muestra un spinner y "Algo salió mal". Ahora que la IA también actúa (envía, reserva, edita y sigue trabajando mientras nadie mira), los momentos no diseñados son peores: hizo algo y el usuario no puede saber qué.
Por lo tanto, el trabajo no es "diseñar el chat". Es: en cada momento, el usuario sabe qué está haciendo la IA, en qué se basa y qué puede hacer a continuación y, cuando actúa por él, qué hizo y cómo deshacerlo.
El objetivo es la confianza calibrada: los usuarios confían en la función tanto como se lo merece, caso por caso. Ambas formas de fallar son fracasos: aceptar sin mirar y rehacer todo a mano.
Lo que toda función de IA debe hacer bien
Revisa estos primero. Son lo que un usuario nota cuando faltan.
- Nunca un spinner vacío. Después de unos dos segundos, el usuario necesita saber qué está pasando, y después de diez, cómo detenerlo o salir.
- Cuatro "no" diferentes. No sabe (sin información), no puede (no es algo que haga), no quiere (no está permitido) y se rompió (fallo del sistema) tienen causas diferentes y pasos siguientes diferentes. Un error genérico para los cuatro hace que los usuarios reintenten cosas que nunca funcionarán.
- No saber es un estado diseñado, no un error. "No pude encontrar eso en tus documentos" es una buena respuesta. Es lo que hace que las otras respuestas sean creíbles.
- Nada parece completo cuando no lo está. Un resultado parcial que parece completo es el estado más peligroso que existe, porque nadie lo revisa.
- Los límites se dicen de antemano. El usuario aprende qué puede y no puede hacer desde la primera pantalla, no al fallar.
- Cada callejón sin salida tiene una salida, y nada de lo que el usuario le dio se pierde: lo que escribió, adjuntó o seleccionó, y el resultado anterior, siguen ahí después de cualquier fallo.
- Verificar cuesta menos que rehacer. Las respuestas muestran en qué se apoyan, en proporción a lo que está en juego: la fuente junto a la afirmación, las páginas cubiertas, la fecha hasta la que está actualizada. Si verificar significa volver a hacer el trabajo, la función no ahorra nada.
- Antes de actuar, muestra; después de actuar, se puede deshacer. Cualquier cosa que envíe, elimine, pague o cambie algo tiene una vista previa y una confirmación cuando no se puede revertir. Confirma lo que importa, no todo: los avisos constantes entrenan a las personas a aprobar sin leer.
- El trabajo realizado sin supervisión vuelve como un informe, no como un aplauso: qué se hizo, qué no, qué no se verificó y por dónde mirar primero.
- Dice solo lo que el sistema puede saber. Sin etiqueta de confianza que el modelo no pueda respaldar, sin "verifiqué" cuando no se verificó nada, sin "lo recordaré" cuando no se almacena nada.
Cómo trabajar
-
Comprende la función antes de dibujar nada. Necesitas: qué hace la IA y para quién; la superficie (lee
references/surfaces.md, incluyendo si el chat es la adecuada); qué lee y qué puede cambiar; qué puede detectar y exponer realmente el sistema (streaming, fuentes, una señal de rechazo, una puntuación de recuperación, tipos de error, eventos de paso); si existe un fallback humano; idioma y registro. Lee lo que el usuario te dio, luego pregunta lo que falta en una sola ronda. Si no puedes preguntar (una ejecución no interactiva o el usuario está ausente), asume la respuesta más probable, marca cada activador que dependa de ella para confirmar y lista las suposiciones. No inventes capacidades: un estado que el sistema no puede detectar no se puede construir. Eso es diferente de una señal que el equipo tiene que construir: si un estado que la función necesita depende de algo que el sistema aún no expone (un tipo de error, una bandera de rechazo), diseña el estado y lista la señal como por construir en la tabla de señales; esa tabla suele ser lo más útil que la ingeniería recibe de ti. -
Establece lo que está en juego. Decide cuánto necesita cada estado.
Lo que está en juego Ejemplos Qué cambia Bajo lluvia de ideas, reescribir una frase, preguntas casuales Toque ligero: regenerar y editar son la red de seguridad Medio resúmenes sobre los que la gente actúa, respuestas sobre la cuenta o datos de la empresa del usuario Fuentes, alcance visible, un claro "no encontrado" Alto dinero, salud, legal, seguridad, cualquier cosa enviada a otros o irreversible Confirmación antes de actuar, evidencia en el camino, una ruta humana, un registro de auditoría Lo que está en juego proviene de lo que la gente hace con el resultado, no de si la IA actúa: un resumen de solo lectura de un contrato del que dependen los abogados es de alto riesgo. Para una función de alto riesgo que no toma acciones, "alto" significa evidencia en el camino, cobertura visible y una ruta humana; no hay nada que confirmar.
-
Revisa las formas en que falla (
references/failure-modes.md). La mayoría son silenciosas: una respuesta fluida pero incorrecta, una omisión, un agente que hace más de lo que se le pidió, una instrucción plantada en un documento. Para cada una que pueda ocurrir aquí, nombra el estado o patrón que la defiende. -
Construye el mapa de estados. Revisa cada estado en
references/states.mdy márcalo:- Aplica - sí, no (con la razón), o solo si existe una señal que no pudiste confirmar.
- Hoy (al revisar algo que existe) - diseñado, incompleto (existe pero le falta algo que lo que está en juego requiere; di qué), genérico (un comodín lo maneja) o falta.
Un estado solo si obtiene un bloque de especificación y una fila en el mapa, cuenta como "por confirmar" en la tira de cobertura en lugar de en el total, y obtiene una tarjeta solo cuando es lo suficientemente probable como para valer la pena dibujarlo.
Si la IA ejecuta varios pasos, usa herramientas por sí sola o trabaja mientras el usuario está ausente, haz lo mismo con los estados de delegación en
references/delegation.md, y completa el nivel de autonomía y la tabla de permisos para cada tipo de acción. Un chat que toma una acción después de que el usuario la confirma no es un agente: el estado 5 (con su pantalla de "después de confirmar" y el deshacer) lo cubre, más una tabla de permisos de tres columnas. No fuerces D1-D12 sobre él. No te saltes el mapa incluso cuando el usuario preguntó por un solo estado: diles qué otros necesita la función. -
Especifica cada estado que aplica en el formato a continuación.
-
Dibuja el tablero. Comienza desde
assets/template.html: una tarjeta por estado, mostrando el componente real en ese estado con el texto final. Una lista de estados en prosa recibe un asentimiento; un tablero donde los vacíos son visiblemente faltantes se corrige. Usa el aspecto propio del producto si te lo dieron (colores, componentes, capturas de pantalla); de lo contrario, mantén el estilo neutral de la plantilla y dilo. Dibuja la superficie real de la función: una función de botón y panel obtiene paneles, no burbujas de chat. Un estado que necesita varias pantallas (antes y después de confirmar) sigue siendo una tarjeta con esas pantallas. Para un diseño nuevo, elimina el bloque de hallazgos de la plantilla y la columna "Hoy" del mapa, y deja que la línea de cobertura diga cuántos estados aplican, cuántos no y cuántos esperan una señal. -
Escribe el texto siguiendo
references/copy.md, en el idioma y registro del producto. -
Escribe el script de prueba y las medidas (
references/measure.md): una entrada que provoque cada estado y qué registrar para ello. -
Revisa contra
references/checklist.mdyreferences/anti-patterns.md, mirando el tablero renderizado, no el código fuente.python scripts/screenshot.py board.html board.pnglo renderiza a una imagen que puedes abrir (los navegadores dentro de la aplicación a menudo rechazan archivos locales); añade--tile 1400para obtenerlo en segmentos legibles cuando el tablero es largo. Si cambias el tablero después de mirar, renderiza de nuevo. -
Entrega el tablero, la especificación y una lista corta de lo que asumiste y lo que necesitas que te respondan. Di qué verificaste y qué no.
Qué leer. Siempre: states.md, copy.md, checklist.md y la sección de surfaces.md para esta superficie. Para una revisión, también failure-modes.md y anti-patterns.md. Solo para agentes (varios pasos, herramientas, trabajo desatendido): delegation.md. measure.md cuando escribas el script de prueba.
Los estados
Catorce estados de respuesta en cinco momentos. Cada uno se detalla en references/states.md con lo que el usuario necesita, el patrón, el antipatrón y el texto.
| Momento | Estado | El usuario pregunta |
|---|---|---|
| Antes | 1. Primer uso | ¿Qué es esto y qué puedo preguntar? |
| 2. Escribiendo | ¿Qué usará? ¿Mi entrada está bien? | |
| Durante | 3. Trabajando | ¿Está haciendo algo? ¿Cuánto falta? ¿Puedo detenerlo? |
| 4. Necesita una aclaración | ¿Qué necesita de mí? | |
| 5. Necesita mi visto bueno | ¿Qué exactamente está a punto de hacer? | |
| Respuesta | 6. Respuesta | ¿En qué se basa? ¿Qué puedo hacer con ella? |
| 7. Respuesta parcial | ¿Qué parte está hecha y cuál no? | |
| 8. Inseguro | ¿Cuánto debería confiar en esto? | |
| No | 9. No sabe | ¿No hay respuesta, o no buscó en el lugar correcto? |
| 10. No puede hacer eso | ¿Quién o qué puede? | |
| 11. No quiere hacer eso | ¿Soy yo, o es la regla? ¿Qué puedo preguntar en su lugar? | |
| 12. Se rompió | ¿Perdí mi trabajo? ¿Lo intento de nuevo? | |
| Después | 13. Corregido | ¿Tomó mi corrección? ¿Volverá a pasar? |
| 14. Transferido a una persona | ¿Quién lo tiene ahora, qué sabe y cuándo? |
Doce estados de delegación, para IA que actúa. Detallados en references/delegation.md.
| Estado | El usuario pregunta |
|---|---|
| D1. Instrucción | ¿Entendió el trabajo y sus límites? |
| D2. Plan | ¿Cómo va a hacerlo y puedo cambiarlo? |
| D3. Permiso | ¿Qué exactamente estoy dejando que toque y por cuánto tiempo? |
| D4. Trabajando desatendido | ¿Sigue en camino? ¿Necesito vigilando? |
| D5. Te necesita | ¿Qué está esperando y qué pasa si no respondo? |
| D6. Redirigido | ¿Tomó la nueva instrucción? |
| D7. Devolución | ¿Qué hizo, qué no hizo y por dónde miro primero? |
| D8. Revisión a escala | ¿Cuáles de estos 140 cambios tengo que mirar realmente? |
| D9. Deshacer y reparar | ¿Puedo revertirlo, todo o solo esto? |
| D10. Salió mal mientras no estaba | ¿Qué tan grave es y dónde se detuvo? |
| D11. Aprende | ¿Qué asume ahora sobre mí? |
| D12. Actúa hacia otros | ¿Qué ven otras personas y saben que fue la IA? |
Para un agente que trabaja en segundo plano sin conversación, varios estados de respuesta son reemplazados por su contraparte de delegación en lugar de dibujarse dos veces: Escribiendo por D1 Instrucción, Trabajando por D4, Necesita una aclaración por D5. Marca el estado de respuesta como "no - ver D4" en el mapa. Un trabajo recurrente (cada noche, cada lunes) tiene una instrucción y un plan permanentes: D1 y D2 son las configuraciones que el usuario revisa una vez y puede ver antes de cada ejecución. En un tablero de este tipo, puedes ordenar las tarjetas por tiempo (antes, mientras trabaja, cuando devuelve) en lugar de por los cinco momentos, si se lee mejor; mantén los números de estado.
Una acción que el producto mismo rechaza por una razón comercial (saldo insuficiente, fecha ya ocupada) no es ninguno de los cuatro "no" sobre la IA: muéstrala como una pantalla del estado 5, con la razón del sistema y lo que el usuario puede cambiar.
Cuatro cosas atraviesan todos ellos y van en el tablero como notas: interrupción, memoria, proactividad (la IA habla primero) y costo (créditos, cuotas, gasto). Ver el final de references/states.md.
Si solo puedes diseñar cinco: Trabajando, No sabe, Se rompió, Respuesta parcial y Necesita mi visto bueno cuando actúa (Devolución cuando trabaja desatendido). Esos son donde la confianza se pierde más rápido.
Formato de especificación
Un bloque por estado, en este orden. Los desarrolladores construyen a partir del activador; sin él, el estado es un deseo.
### 9. No sabe
- **Disparador:** la recuperación no devuelve ningún pasaje por encima del umbral. (por confirmar: el valor del umbral)
- **Muestra:** la burbuja de respuesta, estilo neutral (no el estilo de error).
- **Texto:** "No encontré información sobre licencias por mudanza en las políticas de RR. HH."
- **Acciones:** Reformular · Ver las políticas · Preguntarle a RR. HH.
- **Conserva:** la pregunta, editable.
- **Lleva a:** 2 Escribiendo, o 14 Transferido a una persona.
- **Prueba:** "¿Hay licencia por mudanza?"
- **Medición:** `answer_not_found` con la consulta; vigila la tasa por tema.
- **Pregunta abierta:** ¿puede el sistema distinguir "no hay documentos" de "los documentos existen pero el usuario no tiene acceso"?
Traduce las etiquetas (Trigger, Shows, Copy...) cuando el equipo trabaje en otro idioma: Disparador, Muestra, Texto, Acciones, Conserva, Lleva a, Prueba, Medición, Pregunta abierta.
Conserva es cualquier cosa que el usuario perdería: texto escrito, archivos adjuntos, la selección, el resultado anterior, el trabajo que un agente ya había hecho.
Idioma y registro
Escribe en el idioma que el usuario pida; si no lo dice, usa el idioma de su solicitud y del producto. El registro es elección del producto, no un valor predeterminado: averigua cómo habla ya el producto (usted, vos, tú; formal o cálido) y mantenlo en cada estado. El estado de error es donde los equipos se deslizan a otra voz: un formal "Ha ocurrido un error" dentro de un producto que dice "¡Listo!" en todas partes suena como una empresa diferente.
Pueden estar en juego dos idiomas. El texto (todo dentro de las pantallas dibujadas) está en el idioma y registro del producto. El tablero y la especificación a su alrededor (nombres de estado, encabezados, las etiquetas de la especificación, tus notas) están en el idioma en que trabaja el equipo, que es el idioma en que el usuario te escribió. No dejes los encabezados en inglés de la plantilla en un tablero para un equipo de habla hispana. Los ejemplos en los archivos de referencia están en español formal e inglés; muestran el patrón, así que reescríbelos en el registro del producto en lugar de copiarlos.
La voz propia de la IA: si el producto hace que la IA hable en primera persona, mantén el "yo" para lo que hizo ("No encontré...", "Usé los tres archivos"), no para sentimientos que no tiene ("Me encantaría ayudarte"). Si la función no tiene persona (un botón, un panel), escribe en la voz impersonal del producto ("No se pudo leer el archivo"...).
Referencias
references/states.md- todos los estados detalladosreferences/delegation.md- estados de delegación para agentesreferences/failure-modes.md- modos de fallo silenciososreferences/surfaces.md- superficies donde se ejecuta la IAreferences/copy.md- pautas de redacciónreferences/measure.md- medidas y scripts de pruebareferences/checklist.md- lista de verificaciónreferences/anti-patterns.md- antipatrones que hay que evitarassets/template.html- plantilla del tableroscripts/screenshot.py- script para capturar el tablero