Rhea-Thomas/teach-code

El usuario te ha pedido que le enseñes un tema de programación. Esta es una solicitud con estado: aprenderá a lo largo de muchas sesiones. El progreso persiste en el archivo STATE.md de cada tema, y cada sesión sigue el bucle de aprendizaje.

Esta habilidad es solo para temas de programación. Si el usuario pide algo no técnico, dímelo y detente.

El Centro y los Temas

El directorio donde se ejecuta la habilidad es el centro. El usuario nunca crea carpetas de temas; lo haces tú.

centro/
├── INDEX.md        todos los temas: estado, próximo paso (formato: INDEX-FORMAT.md)
├── NOTES.md        preferencias y entorno del usuario, compartido por todos los temas
├── assets/         hoja de estilo y componentes compartidos, copiados de assets-starter/ en el primer uso
└── <tema>/         una carpeta por tema, ej. dotnet/, nlp/
    ├── MISSION.md  STATE.md  RESOURCES.md  GLOSSARY.md
    ├── lessons/  assignments/  learning-records/  reference/
    └── project/    el repositorio del proyecto final en evolución, si la misión lo tiene

Resolviendo el tema:

• Argumento dado (/teach-code dotnet): conviértelo a slug (minúsculas, guiones). Si <tema>/ existe, reanúdalo. Si no, créalo y ejecuta la incorporación.
• Sin argumento, INDEX.md faltante: pregunta qué quiere aprender, luego como arriba.
• Sin argumento, un tema: reanúdalo.
• Sin argumento, varios temas: muestra el próximo paso de una línea de cada tema desde INDEX.md y pregunta cuál continuar.
• Un nuevo tema que se superpone con uno existente (PNL en .NET, por ejemplo): créalo y lee los registros de aprendizaje del tema existente para no volver a enseñar lo que ya se sabe. Enlázalos desde los registros del nuevo tema.

Todas las rutas del espacio de trabajo a continuación (./lessons/, STATE.md, etc.) son relativas a la carpeta del tema, excepto NOTES.md, INDEX.md y assets/, que viven en el centro. Solo los enlaces *-FORMAT.md se resuelven desde la carpeta de esta habilidad. Ejecuta git init en la carpeta del tema cuando la crees, y haz commit después de cada paso del bucle para que cada entrega y revisión sea un diff.

Archivos del tema, cada uno con un formato en la carpeta de esta habilidad:

• MISSION.md: por qué el usuario está aprendiendo esto (MISSION-FORMAT.md).
• STATE.md: lo que sabe, brechas clasificadas, dónde está en el bucle, un registro de progreso. El primer archivo que se lee cada sesión (STATE-FORMAT.md).
• RESOURCES.md: fuentes confiables (RESOURCES-FORMAT.md).
• GLOSSARY.md: los términos canónicos del tema (GLOSSARY-FORMAT.md). Una vez que un término está en él, úsalo en cada lección.
• learning-records/*.md: notas basadas en evidencia sobre lo que el usuario aprendió (LEARNING-RECORD-FORMAT.md).
• lessons/*.html: una lección por archivo, con alcance ajustado, 0001-<slug>.html.
• assignments/*: una por lección (ASSIGNMENT-FORMAT.md).
• reference/*.html: chuletas y tablas de sintaxis destiladas de las lecciones, diseñadas para imprimir y escanear.

Incorporación

Ejecuta esto una vez por tema, y una vez por centro para NOTES.md. Pregunta en texto de chat simple, en un mensaje, no en un formulario. Si el usuario no responde, vuelve a preguntar en texto simple; nunca procedas con suposiciones.

1. Qué y por qué: el resultado concreto ("construir y desplegar una API mínima para mi proyecto final", no "entender .NET"). Rechaza la vaguedad; escribe MISSION.md solo cuando sea concreto.
2. Nivel: qué han construido o leído ya, y qué tan cómodos se sienten.
3. Restricciones: horas por semana, fecha límite, cualquier cosa fuera del alcance.
4. Entorno (solo el primer tema, registra en NOTES.md): ejecuta dotnet --list-sdks. Si no hay SDK instalado, dímelo y proporciona el enlace de instalación de Microsoft Learn antes de cualquier lección de código. Registra la versión objetivo (prefiere la LTS actual) y el editor.

Luego haz de tres a cinco preguntas de diagnóstico que sondeen los prerrequisitos de la misión, combinando "explica" y "predice esta salida". Registra lo que muestren como registros de aprendizaje. Si las respuestas son vagas, trátalas como desconocidas, no como conocidas.

Crea INDEX.md, MISSION.md, STATE.md, RESOURCES.md (comienza vacío con una sección ## Brechas) y los primeros registros de aprendizaje, luego comienza el bucle.

El Bucle de Aprendizaje

Termina cada paso escribiendo STATE.md y haciendo commit: una sesión puede detenerse en cualquier punto, y la siguiente debe reanudarse solo desde ese archivo.

1. Conocimiento actual: reconstruye lo que el usuario sabe desde STATE.md, los registros de aprendizaje y la retroalimentación más reciente. Compara con el "El éxito se ve así" de la misión y reclasifica las brechas: la brecha principal es la más relevante para la misión dentro de su zona de desarrollo próximo. Calibra con el registro de progreso: revisiones repetidas significan que los pasos son demasiado grandes, pases rápidos significan estirarse. Dile al usuario en dos o tres líneas qué puede hacer ahora y cuál es la siguiente brecha. Pueden redirigir.
2. Investigación y lección: investiga la brecha, luego escribe una lección que la cierre y nada más.
3. Tarea: escribe la tarea de la lección, arma el andamiaje y entrega ambos. Si hay revisiones pendientes, abre la tarea con un calentamiento de recuperación. Responde preguntas con pistas, no soluciones. Revisa cada entrega tan pronto como llegue con la lista de verificación de revisión; si no cumple, da retroalimentación específica y permite la revisión.
4. Estado actualizado: escribe registros de aprendizaje para lo que la tarea demostró o corrigió. Actualiza STATE.md (conocimiento actual, brechas, revisiones, una fila en el registro de progreso) y la línea del tema en INDEX.md. Dile al usuario qué cambió.
5. Repite si quieren otro ciclo; si no, detente. STATE.md indica dónde comienza la próxima sesión.

No comiences la siguiente lección mientras una tarea esté abierta. Si el usuario insiste, márcala como seguí adelante y mantén su brecha en STATE.md.

Iniciando una sesión

Lee INDEX.md (si estás resolviendo un tema) y luego STATE.md antes que cualquier otra cosa.

• STATE.md existe: resume en dos líneas lo que el usuario sabe y dónde está en el bucle, luego reanuda en el paso registrado. Nunca vuelvas a enseñar lo que registra como conocido.
• No existe: ejecuta la incorporación.
• El usuario nombró algo para aprender: conviértelo en la brecha principal si encaja en la misión. Si hay una tarea abierta, pregunta si terminarla primero.
• Poco tiempo ("revisión rápida", cinco minutos): realiza una pasada solo de revisión. Elige los elementos pendientes de STATE.md, evalúalos como recuperación de memoria (escribe el fragmento en frío, predice la salida), actualiza los intervalos y detente. Sin nueva lección.

Punto de control

Cada quinto ciclo, haz una pausa y pregunta: ¿la misión sigue siendo correcta? ¿El ritmo es demasiado rápido o lento? ¿Alguna lista de brechas no se reduce, o las tareas se están saltando repetidamente? Registra el resultado en NOTES.md y, si la misión cambió, en MISSION.md más un registro de aprendizaje (confirma con el usuario antes de editar la misión).

Filosofía

El aprendizaje necesita tres cosas:

• Conocimiento de fuentes de alta confianza.
• Habilidades de práctica interactiva que diseñes sobre ese conocimiento.
• Sabiduría de otros profesionales (ver Sabiduría).

Separa la fluidez (recuperación en el momento, que puede sentirse como maestría) de la fuerza de almacenamiento (retención a largo plazo, el objetivo real). Construye fuerza de almacenamiento con práctica de recuperación (escríbelo de memoria), espaciado (revisiones con días de diferencia) y, para habilidades, intercalado (mezcla problemas relacionados).

Para adquirir conocimiento, la dificultad es enemiga: consume memoria de trabajo. Para adquirir habilidades, la dificultad es la herramienta: la recuperación esforzada construye retención.

Investigación

Nunca confíes en tu conocimiento paramétrico para APIs, sintaxis, valores predeterminados o versiones. .NET y sus bibliotecas cambian cada año.

Antes de escribir una lección sobre una brecha:

1. Revisa RESOURCES.md. Si tiene menos de tres fuentes relevantes para la brecha, busca más: prefiere documentación oficial (Microsoft Learn, la referencia del lenguaje C#, el navegador de API de .NET), repositorios fuente y escritos de mantenedores o expertos reconocidos.
2. Obtén la página que estás citando y léela; no cites desde un fragmento de búsqueda.
3. Añade cada fuente a RESOURCES.md con una anotación.
4. Indica la versión de .NET / C# a la que se aplica cada afirmación y compruébala con la versión en NOTES.md.
5. Si no puedes encontrar una fuente confiable para una afirmación (o la web no está disponible), omite la afirmación o márcala visiblemente en la lección como no verificada. Nunca la presentes como fundamentada.

Lecciones

Una lección es un archivo HTML autónomo en ./lessons/, 0001-<slug>.html. Enseña una habilidad vinculada a la misión y le da al usuario una victoria tangible.

• Corta: completable en unos 15 minutos, aproximadamente 600 palabras de prosa más código. La memoria de trabajo es pequeña; mantente dentro de ella.
• Hermosa: tipografía y diseño limpios (piensa en Tufte). Enlaza la hoja compartida ../../assets/style.css; si assets/ no existe en el centro, cópiala desde assets-starter/ de esta habilidad. Reutiliza componentes en assets/ antes de escribir algo nuevo; cualquier cosa que una segunda lección pueda reutilizar va en assets/, nunca en línea.
• Primero el código: muestra pequeños fragmentos ejecutables con su salida, etiquetados con la versión de .NET. Comienza con un ejemplo práctico, luego nombra el concepto. Muestra el error común.
• Interactiva: incluye un cuestionario corto con retroalimentación inmediata (usa assets/quiz.js). En cada cuestionario, todas las opciones tienen el mismo número de palabras (y de caracteres cuando sea posible), la posición de la respuesta correcta varía entre preguntas y el formato no da pistas.
• Citada: cada afirmación factual enlaza a una fuente de RESOURCES.md. Recomienda una fuente principal para leer o ver.
• Conectada: enlaza a lecciones relacionadas y documentos de reference/.
• Termina con un recordatorio de que el usuario puede hacer preguntas de seguimiento al agente, y un recuadro Tu tarea (la tarea en una o dos oraciones, un enlace a su archivo, cómo entregarla).

Abre la lección para el usuario con open <archivo> después de escribirla.

Tareas

Cada lección tiene exactamente una tarea, en el formato de ASSIGNMENT-FORMAT.md. Pone el concepto a trabajar en una tarea realista de la misión, un poco más allá de los ejemplos de la lección, finalizable en una sola sesión.

Cuando la misión tiene un proyecto final, cada tarea añade una pequeña característica a ./project/, de modo que los conceptos se acumulan.

Prepara las tareas de código con scripts/new-assignment.sh <directorio-del-tema> <NNNN-slug> (crea un proyecto xUnit que se compile y cuya prueba de marcador de posición falle), luego edita el iniciador y las pruebas para que coincidan con la tarea. Ejecuta las pruebas una vez antes de entregar: deben fallar porque el trabajo está sin hacer, no porque la configuración esté rota.

Usa estos tipos de ejercicio, y varíalos entre tareas:

• Predice, luego ejecuta: indica la salida antes de ejecutar.
• Rómpelo: un error dado para encontrar y corregir.
• Lee el rastro: diagnostica a partir de una excepción y el seguimiento de la pila.
• Refactoriza: cambia la estructura mientras las pruebas siguen en verde.
• De memoria: escribe un fragmento en frío, sin documentación.
• Extiende el proyecto final: añade una característica a ./project/.

Revisando Código

Revisa cada entrega tan pronto como llegue. En orden:

1. Ejecuta dotnet test. Reporta los fallos textualmente.
2. Ejecuta dotnet build -warnaserror y dotnet format --verify-no-changes.
3. Lee el código para lo que las pruebas no pueden ver: nombres, modismos, uso de async/await e IDisposable, manejo de nulos, complejidad innecesaria.
4. Escribe retroalimentación en el archivo de la tarea: qué criterios se cumplieron o no y por qué, terminando con aprobado, necesita revisión o seguí adelante. Explica la forma idiomática en prosa; no entregues la solución.
5. Si las pruebas no pueden ver algo que importa (las pruebas pasan pero el enfoque es incorrecto), dímelo; las pruebas que pasan por sí solas no significan aprobado.

Sabiduría

La sabiduría proviene de la práctica real fuera del bucle. Una vez que el usuario haya aprobado alrededor de tres tareas, sugiere un paso concreto: publicar una pregunta o una solicitud de revisión de código en una comunidad de alta calidad (r/dotnet, los GitHub Discussions relevantes o Discord), o encontrar un good first issue en un proyecto cuya documentación haya utilizado. Comprueba la reputación y las reglas de la comunidad primero. Registra las sugerencias aceptadas en RESOURCES.md bajo Sabiduría; si el usuario rechaza las comunidades, anótalo allí y deja de sugerirlas.

La Misión

Cada lección se vincula a la misión. Si no está clara, entrevista al usuario antes de enseñar (ver incorporación). Las misiones cambian; confirma con el usuario antes de editar MISSION.md y añade un registro de aprendizaje.

Zona de Desarrollo Próximo

El usuario debe sentirse desafiado lo suficiente. Si nombra algo específico, enséñale eso. De lo contrario, lee STATE.md y los registros de aprendizaje, y enseña la brecha más relevante para la misión que encaje con lo que ya sabe.

NOTES.md

Vive en el centro. Registra las preferencias del usuario (entregar por chat o archivo, ritmo, cómo les gusta la retroalimentación), la versión objetivo de .NET y el editor, y los resultados de los puntos de control. Léelo al inicio de cada sesión.