rzhang569/guía-de-estudio

Guía de estudio

Produces una página HTML autónoma por examen, construida a partir de una carpeta del curso con archivos planos mediante scripts/build.py. La página tiene tres partes:

• Notas, una sección por conferencia. Cada afirmación cita una página de diapositiva. Cada tema incluye recuadros en lenguaje sencillo, ejemplos resueltos, figuras y recuadros rojos de "trampa". Un recuadro de práctica al final de cada sección permite al estudiante evaluarse justo después de leer.
• Un centro de práctica con cuatro pestañas:
  • un banco de práctica con retroalimentación instantánea y una explicación para cada opción;
  • respuestas cortas paso a paso con crédito parcial;
  • exámenes simulados cronometrados extraídos de su propio conjunto, en las mismas proporciones del examen real;
  • un cuaderno de errores que se llena solo.
• Un informe de progreso, que la página mantiene para ti. Lo lees más tarde y escribes nuevos ejercicios que se centren en lo que el estudiante realmente falló.

El motor (assets/engine.js) y los estilos (assets/page.css) están terminados y probados, así que tu trabajo es el contenido y las preguntas. La mayor parte de lo que hace útil a una página está en los archivos de referencia; léelos cuando llegues a ese paso.

Cuando estés a punto de...	Lee
escribir las secciones de las conferencias	references/content-standard.md
escribir o auditar preguntas, o calibrar el examen simulado	references/question-bank.md
verificar un nombre de campo, el formato del progreso o la documentación de la base de datos	references/data-format.md

examples/demo/ es un curso pequeño completo (ficticio PROB 101, tres conferencias). Cuando no estés seguro de cómo debería verse algo, copia el patrón de sus fuentes: sections/*.html, practice.json, mock.json y short.json.

No leas assets/engine.js, assets/page.css ni ningún review.html generado. build.py los incluye, tienen decenas de miles de tokens y nada en ellos necesita tus ediciones.

En los comandos a continuación, <skill-dir> es la carpeta que contiene este SKILL.md. Si no se encuentra python3 (común en Windows), usa python o py -3.

1. Averiguar qué es el examen

Obtén estos datos antes de escribir nada. Búscalos cuando puedas y pregúntale al estudiante solo lo que no puedas encontrar:

• Examen: fecha y hora, duración en minutos, qué conferencias entran en el temario, el formato y los materiales permitidos. Formato significa tipos de preguntas, cuántas de cada una y sus puntos. Materiales significa hojas de apuntes, una calculadora o nada.
• Fuentes: diapositivas (PDFs o enlaces), lecturas, el sitio web del curso y cualquier pregunta oficial de práctica, resultados de cuestionarios o examen de muestra.
• Estudiante: el idioma en el que quiere la página (lang: zh o en para la interfaz; escribe el contenido en su idioma) y qué tan sólidos son sus conocimientos previos. Un estudiante que dice "estoy perdido" necesita recuadros en lenguaje sencillo en casi todos los temas.

Si puedes navegar, investiga el curso tú mismo: la página del calendario, el programa de estudios y los resultados publicados de los cuestionarios. Busca patrones que valga la pena contarle al estudiante, como "las preguntas de verificación en clase aparecen justo después de una diapositiva específica" o "el banco oficial dice que usa el mismo formato que el examen". Pon la logística en la sección principal (hero) de la página.

Verifica la política de IA del curso en el programa de estudios. Algunos cursos prohíben el material de estudio generado por IA o la ayuda de IA en trabajos calificados. Si la política lo prohíbe, díselo al estudiante antes de construir. Nunca pongas respuestas de tareas calificadas en la página.

2. Calibrar el examen simulado sin spoilers

Los estudiantes a menudo quieren guardar el examen de muestra oficial para una ejecución cronometrada. Entonces no leas sus preguntas; mídelo en su lugar:

python3 <skill-dir>/scripts/count_exam.py sample_exam.pdf

El script nunca imprime el texto de la pregunta, opción o escenario. Imprime:

• el número de páginas y preguntas, y las opciones por pregunta;
• valores de puntos, el límite de tiempo y las instrucciones de portada (calculadora, apuntes);
• encabezados de partes y rangos de preguntas que comparten un escenario ("Preguntas 11-14…");
• los números de las preguntas que remiten a material anterior.

Usa la salida para establecer las secciones del simulado (tipos y cantidades) y el límite de tiempo. Una pregunta que remite a algo anterior, como una respuesta corta que reutiliza un escenario anterior, pertenece a ese escenario cuando describas la estructura del examen.

Si el script no puede decirte algo, repórtalo como desconocido y pídele al estudiante que mire la portada. No escribas tu propia sonda que imprima palabras o números del interior de las preguntas. Incluso un "total" o "%" suelto da pistas sobre el tema de una pregunta, y los números en una ecuación delatan la pregunta.

Pregunta antes de abrir cualquier muestra o clave de respuestas. Incluso cuando el estudiante permita leerlo, úsalo solo para calibrar (estructura, dificultad, estilo). Nunca copies sus preguntas o escenarios en la página.

3. Configurar la carpeta del curso

python3 <skill-dir>/scripts/build.py --init <course-dir>

Esto copia el curso de demostración. Luego edita course.json:

• title, lang y lectures. Las etiquetas de las conferencias son exactamente lo que usan las preguntas y los grupos, ej. "L1" o "L5–L6".
• storageKey: única por curso y examen, ej. "bio201-mt1". El progreso se almacena bajo ella, así que nunca la cambies una vez que el estudiante haya empezado.
• mock.sections: una entrada por tipo de pregunta, en orden de examen, con cantidades que coincidan con el examen real.
• mock.minutes: límites entre los que elegir. Incluye el real; si el simulado omite preguntas largas, ofrece también uno proporcionalmente más corto.

Elimina las secciones y preguntas de demostración a medida que las reemplaces. Consulta references/data-format.md para cada campo.

4. Escribir las secciones

Escribe un archivo por conferencia en sections/ (10-l1.html, 20-l2.html, …), más 00-hero.html para la logística y una lista final de trampas. Cada conferencia es un <section class="part" id="...">. Su recuadro de práctica aparece automáticamente cuando un grupo de práctica apunta a ese id con "sec".

references/content-standard.md tiene la receta completa y el HTML para cada componente. En resumen: cita cada afirmación, abre las conferencias difíciles con un glosario y analogías, da a cada tema un título de una línea, un ejemplo concreto antes de cualquier fórmula, un recuadro en lenguaje sencillo, una figura donde una imagen ayude y un recuadro de trampa para lo que las preguntas de verdadero/falso retuercen.

5. Escribir las preguntas

Hay tres bancos. references/question-bank.md tiene las reglas y la lista de verificación de auditoría.

• practice.json: 8-15 preguntas por conferencia. Mezcla opción única, verdadero/falso, selección múltiple y completar, más una tarjeta didáctica ocasional. Cada opción tiene su propia explicación.
• mock.json: sus propias preguntas, nunca copias de los ítems de práctica. Apunta a aproximadamente el doble de lo que un examen extrae de cada tipo, para que los exámenes repetidos difieran. Coincide con el estilo del examen real.
• short.json (opcional): versiones paso a paso de los tipos de respuesta corta del examen. Cada paso es un completar tolerante, una opción o una autocomprobación contra la respuesta modelo.

6. Construir y verificar

python3 <skill-dir>/scripts/build.py <course-dir>

Los errores detienen la construcción. Las advertencias provienen de las comprobaciones del banco de preguntas; corrígelas a menos que tengas una razón para no hacerlo. Marcan patrones como:

• la respuesta correcta es la opción más larga en demasiadas preguntas;
• una letra es la respuesta mostrada con demasiada frecuencia;
• cada selección múltiple tiene el mismo número de respuestas;
• una pregunta del simulado es una pregunta de práctica con números nuevos.

Añade --strict para hacer que las advertencias terminen la construcción con código de salida 2 (la página aún se escribe), para que puedas seguir corrigiendo hasta que esté limpia. Luego abre <course-dir>/review.html en un navegador y verifica:

• la consola no muestra errores y las fórmulas se renderizan;
• responder una pregunta de práctica, un paso de respuesta corta y un examen simulado completo funciona;
• a 375 px de ancho, nada desplaza la página horizontalmente (las figuras y tablas se desplazan dentro de sus propios recuadros);
• ningún texto en una figura se superpone a una línea, una punta de flecha u otro texto (toma una captura de pantalla).

7. Entregar

• Local (cualquier agente): proporciona la ruta del archivo. El progreso se guarda en el localStorage de ese navegador. El botón Exportar progreso en el centro de práctica le da al estudiante un JSON para pegarlo de vuelta.
• Artefacto de claude.ai (solo Claude; experimental, aún no probado de extremo a extremo): publica el HTML construido y concede la capacidad db. Si window.claude.use("db") está disponible, el motor refleja el progreso en los documentos progress/practice y progress/mock y mantiene un resumen en progress/report. Antes de confiar en ello, responde una pregunta en la página publicada y lee progress/report de vuelta. Si falta el documento, dile al estudiante que use Exportar progreso en su lugar.

Dile al estudiante en dos o tres líneas cómo usar la página: leer una sección, hacer su recuadro de práctica, exámenes simulados cerca del final y el cuaderno de errores el día anterior.

8. Cerrar el ciclo

Cuando el estudiante regrese, lee su progreso antes de cambiar nada. Usa el JSON exportado que pegue o envíe (su campo report), o el documento progress/report de la base de datos si la sincronización del artefacto funciona. El informe enumera:

• precisión en el primer intento por conferencia;
• cada pregunta de práctica fallada con lo que respondieron y la respuesta correcta;
• pasos de respuesta corta que fallaron;
• historial de exámenes simulados, más las preguntas incorrectas y marcadas del último examen.

Luego:

1. Nombra los puntos débiles en pocas líneas. Cuenta las conferencias por debajo de aproximadamente un 80% de precisión en el primer intento, conceptos erróneos repetidos y pasos de respuesta corta que siguen fallando. También cuenta las preguntas marcadas como inseguras pero respondidas correctamente; esos son conocimientos endebles también.
2. Escribe nuevos ejercicios para cada punto débil. Vuelve a preguntar el mismo concepto con diferentes palabras, números o escenarios; nunca repitas la pregunta que fallaron. Añádelos a practice.json con nuevos ids, y a mock.json si el conjunto del simulado es escaso allí.
3. Corrige la explicación, no solo las preguntas. Si un concepto erróneo se repite, la sección probablemente lo explica mal. Añade un recuadro en lenguaje sencillo, un ejemplo resuelto o una figura dirigida exactamente a esa confusión.
4. Reconstruye, luego dile al estudiante qué cambió y dónde.

Mantener válido el progreso guardado al editar

Los registros se indexan por storageKey, id de la pregunta e índice de opción original. Por lo tanto:

• mantén el storageKey y los ids existentes;
• no reordenes, insertes ni elimines opciones en preguntas que hayan sido respondidas (añade una nueva pregunta en su lugar);
• no reutilices un id antiguo para una pregunta diferente;
• si el significado o la respuesta de una pregunta cambia, dale un nuevo id y elimina el antiguo. Los registros de ids eliminados se ignoran, no se malinterpretan.

El motor baraja el orden en que se muestran las opciones con una semilla del id, por lo que los índices almacenados se mantienen correctos. Para cambiar qué letra se muestra como respuesta, establece "show" (consulta references/data-format.md) en lugar de reordenar las opciones. Corregir errores tipográficos o redacción en enunciados y explicaciones siempre es seguro, y también lo es editar el HTML de las secciones.

Lo que pidieron los estudiantes

Estas lecciones provienen de la creación de páginas de revisión que se usaron para exámenes reales:

• Las explicaciones abstractas no calaban. Los estudiantes pidieron primero números concretos ("lanza una moneda 10 veces…"), luego la fórmula, con las derivaciones plegadas y etiquetadas como que no entran en el examen.
• Estudiar varias conferencias antes de practicar era agotador. Por eso cada sección termina con su propio recuadro de práctica.
• La rigurosidad con el formato era exasperante, como ser marcado como incorrecto por 1/2 en lugar de 0.5. El motor compara respuestas numéricas por valor; enumera variantes de texto en accept.
• Los estudiantes aprenden patrones de respuesta rápido. La respuesta correcta solía ser la opción más larga, cada selección múltiple tenía 3 respuestas y la respuesta correcta siempre era B. La compilación audita las dos primeras; el motor baraja el orden de visualización.
• Un examen simulado que reutilizaba preguntas de práctica medía memoria, no comprensión. Por eso el conjunto del simulado es independiente.
• Los estudiantes querían poder seleccionar texto de opción para copiarlo y un temporizador que se enviara solo cuando el tiempo se acabe.