teach y wait-what: aprende de verdad con tu agente y para cuando no entiendas lo que te dice

Casi todas las skills de esta guía ayudan al agente a entenderte a ti. Las dos últimas hacen lo contrario: te ayudan a entender tú lo que hace y dice el agente. teach convierte una carpeta en un espacio de aprendizaje de varias sesiones, con lecciones, referencias y un registro de lo que ya sabes. wait-what es un comando de una línea para cuando el agente te suelta un mensaje que no has entendido. Una sirve para aprender a fondo y la otra para no perderte en el momento.

Es la decimocuarta y última parte de la guía de las skills de Matt Pocock (repositorio mattpocock/skills, licencia MIT). Las dos se invocan a mano.

wait-what: "espera, no te he entendido"

Es la skill más corta del repositorio. Su contenido completo es una instrucción al agente, que traducida dice:

Espera, no entiendo a dónde has llegado. Vuelve a planteármelo: dame un poco de contexto, habla en inglés técnico simplificado ASD-STE100 y usa el lenguaje ubicuo de GLOSSARY.md (sigue GLOSSARY-MAP.md hasta el correcto si el repositorio tiene más de uno).

Tres ingredientes:

• Contexto: lo que te faltaba para seguir el razonamiento.
• ASD-STE100: el Simplified Technical English, un estándar de la industria aeroespacial para documentación técnica con vocabulario controlado y frases cortas. Le da al agente una referencia concreta de "explícalo simple".
• El glosario del proyecto: el vocabulario que acordasteis con grill-with-docs, en lugar de jerga nueva.

Se puede lanzar en mitad de cualquier otra skill. ask-matt la describe como el correctivo a posteriori, y deja claro cuál es la cura preventiva: un lenguaje compartido acordado pronto es lo que evita que la jerga aparezca.

Un detalle: el estándar pide inglés simplificado. Si trabajas en español, añade "en español" al invocarla (/wait-what en español), o el agente puede responderte en inglés.

teach: un espacio de aprendizaje de varias sesiones

/teach parte de que quieres aprender algo a lo largo de varias sesiones. Trata la carpeta actual como un espacio de enseñanza con estado:

MISSION.md              # por qué quieres aprender esto
RESOURCES.md            # fuentes fiables que se han encontrado
NOTES.md                # tus preferencias y notas del agente
lessons/0001-*.html     # lecciones de una sola página
reference/*.html        # chuletas y glosarios para repasar
learning-records/0001-*.md  # lo que ya has aprendido
assets/                 # hoja de estilos y componentes reutilizables

La misión primero

Todo se ancla en MISSION.md: el motivo real por el que quieres aprenderlo, cómo se ve el éxito, tus restricciones y lo que queda fuera. Si no está claro, la primera tarea del agente es preguntarte por qué. Sin misión, las lecciones se vuelven abstractas y no hay forma de saber qué enseñar después.

Conocimiento, habilidad y sabiduría

La skill separa tres cosas:

• Conocimiento: viene de fuentes de alta confianza, recogidas en RESOURCES.md. La regla: "nunca te fíes de tu conocimiento paramétrico". Las lecciones llevan citas a las fuentes.
• Habilidad: se adquiere con lecciones interactivas basadas en un bucle de feedback lo más inmediato posible (cuestionarios, tareas ligeras en el navegador, pasos guiados).
• Sabiduría: solo llega practicando fuera, así que el agente intenta responder pero te deriva a una comunidad (un foro, un grupo local, una clase), salvo que digas que no quieres.

Retener, no solo entender

Distingue la fluidez (recordar en el momento, que da una falsa sensación de dominio) de la fuerza de almacenamiento (recordar a largo plazo, que es el objetivo). Para lo segundo usa dificultad deseable: práctica de recuperación, espaciado e intercalado. Para el conocimiento nuevo, en cambio, la dificultad es el enemigo, porque gasta la memoria de trabajo que necesitas para entender.

Hasta los cuestionarios tienen reglas: todas las respuestas con el mismo número de palabras, y la correcta en posiciones distintas, para no dar pistas por el formato.

Las lecciones

Cada lección es un HTML autocontenido en lessons/, corto, que se completa rápido y da una victoria tangible. Debe ser bonita ("piensa en Tufte"), enlazar a otras lecciones y referencias, recomendar la mejor fuente primaria que se encontró y recordarte que puedes preguntar al agente. El nivel lo marca la zona de desarrollo próximo: el agente lee tus learning-records para enseñarte justo lo siguiente que puedes aprender, ni más fácil ni más difícil.

Los registros de aprendizaje funcionan como los ADR del código: un párrafo con lo aprendido y por qué cambia lo que toca enseñar después.

Cómo se combinan

Las dos atacan el mismo hueco, que el humano se quede atrás respecto al agente, en dos escalas de tiempo:

• wait-what en segundos: un mensaje concreto que no entendiste.
• teach en semanas: un tema entero que necesitas dominar.

Y comparten la base del glosario. wait-what reexplica con el GLOSSARY.md del proyecto; teach crea su propio glosario en reference/ y lo respeta en cada lección. Si al usar wait-what descubres que te falta un concepto de fondo (qué es una costura, qué es un módulo profundo), es la señal para abrir una carpeta y lanzar /teach sobre ese tema.

Un ejemplo con esta guía: si después de leer la parte 8 los módulos profundos te siguen pareciendo abstractos, /teach diseño de módulos profundos crea una misión, busca fuentes primarias (el libro de Ousterhout, el de Feathers) y te da una primera lección corta con un ejercicio de "prueba del borrado" sobre tu propio código.

Errores frecuentes

• Saltarse la misión en teach. Sin ella las lecciones son genéricas.
• Usar teach en la carpeta del proyecto. Crea muchos ficheros; mejor una carpeta propia para cada tema.
• Esperar que wait-what responda en español sin pedirlo. El estándar que cita es inglés simplificado.
• Usar wait-what en lugar de un glosario. Es un parche; la cura es grill-with-docs desde el principio.

Preguntas frecuentes

¿teach sirve para temas que no son de programación? Sí. La skill pone ejemplos como yoga o física teórica.

¿Dónde se ven las lecciones? Son ficheros HTML en lessons/; el agente intenta abrirlos en el navegador con un comando.

¿wait-what necesita un GLOSSARY.md? No, pero funciona mejor con él: sin glosario, solo tiene el contexto y la regla de lenguaje simple.

Resumen de la guía

Con esta parte cerramos las 27 skills del plugin mattpocock-skills. El recorrido completo:

1. Qué son e instalación: setup-matt-pocock-skills y ask-matt.
2. grill-me y sus ejemplos reales.
3. grill-with-docs y domain-modeling.
4. to-spec y to-tickets.
5. tdd y diagnosing-bugs.
6. implement y code-review.
7. improve-codebase-architecture y codebase-design.
8. prototype y research.
9. wayfinder y triage.
10. handoff y to-questionnaire.
11. pr y wizard.
12. retro y writing-for-agents.

Si solo vas a usar una, que sea grill-with-docs dentro de un repositorio o grill-me fuera de él.