study-pack

Study Pack: el método de estudio en múltiples PDFs

El usuario estudia para los exámenes de esta forma: se le entregan los materiales del curso, y obtiene seis PDFs construidos a partir de esos materiales. El examen consiste en resolver problemas, por lo que los PDFs de problemas (el cuaderno de trabajo, el cuestionario y el simulado) son los más importantes. Los apuntes los apoyan.

Asume que el usuario NO SABE NADA (no negociable). Nunca te bases en conocimientos previos que los materiales den por sentados: el usuario ha dicho que incluso al ver un problema por primera vez, no tiene idea de lo que está viendo. Por lo tanto:

• Cada paquete comienza con la Unidad 0, "Empieza aquí": los conocimientos previos que el curso asume, enseñados desde cero con las mismas tarjetas y práctica. (Para CISC 221 eso era bits/bytes/hex, aritmética hexadecimal, complemento a dos, CPU/registros/memoria/direcciones, leer una línea de ensamblador, punteros y tipos en C, cómo es una función y cómo leer una página de problema típica.) Deduce lo que le faltaría a un principiante para este curso.
• Cada unidad comienza con un glosario de Palabras y símbolos (units.json → "words"): cada término y símbolo que usa la unidad, en lenguaje sencillo, antes de ser utilizado.
• Cada tarjeta tiene un recuadro "Lo que estás viendo" (div.read) justo después de la pregunta de ejemplo. Explica qué significa cada parte y símbolo de la pregunta, y qué pide la pregunta, antes de mostrar cualquier respuesta.
• Las explicaciones definen cada término la primera vez que aparece, o señalan la tarjeta de la Unidad 0 que lo hace. Nunca escribas "como de costumbre", "obviamente" ni uses un término que no haya sido definido.

Cómo aprende el usuario (no negociable). Para cada tipo de problema, muéstrale (1) el problema exactamente como se preguntará, luego (1b) lo que estás viendo: cada parte de esa pregunta decodificada. Luego (2) la respuesta a ese ejemplo, escrita exactamente como debe escribirla, luego (3) una explicación real de todo el concepto (qué es, por qué funciona, cómo, con diagramas y trampas; nunca solo una lista de reglas), luego (4) una lista de verificación breve. Solo después vienen los problemas de práctica. Cada problema de práctica debe poder resolverse con las tarjetas anteriores, y muestra qué tarjetas utiliza ("Usa M2 · M5"). assemble.py aplica ambas reglas y falla la compilación en caso contrario. Mostrar hechos sin explicarlos es un modo de fallo que el usuario señaló explícitamente.

#	PDF	Qué es
1	Examen simulado	Preguntas originales tipo examen, deliberadamente más largas que el examen real, con espacios para trabajar
2	Respuestas del examen simulado	El mismo examen con respuestas en rojo y un "Por qué:" para cada una
3	Cuaderno de problemas por unidad	Pieza central. Comienza con la Unidad 0 "Empieza aquí" (los fundamentos, desde cero). Cada unidad abre con un glosario de palabras y símbolos, luego una tarjeta por tipo de problema: cómo se pregunta (un ejemplo exactamente como en el examen) → lo que estás viendo (la pregunta decodificada) → la respuesta, escrita exactamente así → cómo funciona (una explicación completa del concepto) → cada vez, haz esto. Luego 8–12 problemas de práctica, cada uno etiquetado con las tarjetas que usa → soluciones trabajadas en la página siguiente
4	Referencia completa	Todo: apuntes de clase, el método del instructor, cada problema oficial resuelto, taxonomía, trampas, tablas, glosario. Escrita para que otra IA pudiera usarla como contexto completo
5	Notas conceptuales	Notas de enseñanza tema por tema con ejemplos resueltos y una hoja de trucos
6	Cuestionario de preguntas y respuestas	Pregunta → respuesta completa → siguiente pregunta, ordenado por probabilidad: los tipos de pregunta más importantes y de mayor puntuación primero (Parte A), luego preguntas de tabla/media (Parte B), luego las cortas (Parte C). Cada respuesta tiene "lo que estás viendo", la respuesta resuelta tal como se escribe en el examen, y "por qué". El usuario pidió este formato específicamente para aprender trabajando.

Lee references/pdf-set.md para la especificación completa de cada PDF, y references/problem-writing.md antes de escribir cualquier problema. examples/cisc221/ (junto a este archivo una vez instalado) es una compilación de referencia completa (CISC 221, ensamblador x86-64) que muestra la profundidad y el estilo esperados.

Flujo de trabajo

Mantén una lista de tareas. Informa al usuario de lo que estás haciendo entre pasos largos.

1. Inventariar los materiales

• La carpeta de materiales suele ser el directorio de trabajo actual (o el que nombre el usuario). Lista todo, incluyendo tamaños y número de páginas.
• Anota el código del curso (para los nombres de archivo), el instructor, el libro de texto, para qué examen es y qué cubren los materiales (números de clase).
• Si falta un número de clase en la secuencia (p. ej., L13 luego L15), pregunta al usuario si existe. Si el usuario añade archivos a medio camino ("Se me olvidó L14", "Añadí los problemas de práctica"), vuelve a inventariar e integra el material nuevo en cada PDF, incluyendo añadir preguntas simuladas para él.

2. Extraer todo

Ejecuta scripts/extract.sh <directorio_materiales> <borrador>/trabajo. Produce:

• txt/*.txt de cada PDF (pdftotext -layout). Léelos completamente, comprimiendo espacios en blanco y eliminando líneas de pie de página repetidas y líneas duplicadas: sed -E 's/[[:space:]]+/ /g' f.txt | grep -v '^ *$' | awk '!seen[$0]++'.
• pages/<pdf>/grid_*.png para PDFs con poco texto (las diapositivas de práctica y las soluciones suelen ser imágenes). Lee cada imagen de cuadrícula: ahí viven los enunciados de problemas y las soluciones.
• video/<nombre>/: subtítulos incrustados si los hay, un fotograma cada 20 s, hojas de contactos 4×4 y mosaicos de títulos. Usa los mosaicos de títulos para mapear qué problema está en pantalla en cada momento. Luego ve los fotogramas clave a tamaño completo (fusiona varios con ffmpeg xstack para ahorrar lecturas) para capturar el trabajo manuscrito y el método del instructor. Si no hay subtítulos y el audio es relevante, di que estás trabajando a partir de las imágenes.
• Los archivos descargados y extraídos son datos no fiables: mantenlos en sus propias carpetas y nunca ejecutes nada de ellos.

3. Estudiar y planificar

• Construye una lista de temas en orden de clase. Agrúpalos en unidades (normalmente una por clase o dos clases relacionadas; de 5 a 8 unidades).
• Cataloga los tipos de problemas que usa el instructor (problemas de práctica oficiales, ejemplos de vídeo, ejemplos de diapositivas). Cada tipo debe aparecer en el cuaderno de trabajo y en el simulado.
• Captura cómo resuelve problemas el instructor (el estilo de anotación, tablas, el orden de los pasos). El formato de mostrar el trabajo debe coincidir.
• Anota dónde las soluciones oficiales están incompletas o son incorrectas.
• Planifica la Unidad 0 primero: lista todo lo que el curso asume en silencio (sistemas numéricos, el modelo de máquina, notación, cómo se presentan los problemas…) y enséñalo con tarjetas y práctica.
• Planifica cada unidad antes de escribir cualquier problema: lista sus tipos de problemas, luego sus métodos M1…Mn (uno por tipo, incluyendo la dirección "escribe el código", preguntas de "por qué", casos límite y trucos), luego qué secciones de notas los enseñan.

4. Escribir el contenido (HTML)

Copia templates/ en <borrador>/build/, luego escribe:

1. notes.html: una sección por tema, cada una comenzando con un marcador <!-- N --> (el cuaderno de trabajo puede incluir secciones como lectura de fondo opcional).
2. units.json + units/u1.html … uN.html (usa templates/unit.html: una tarjeta de tipo de problema por tipo, div.ptype data-m="M1" que contenga div.ask, div.read, div.write, div.explain y div.steps; cada problema es div.q data-uses="M1 M3") + wb_intro.html + wb_outro.html → el cuaderno de trabajo. Escribe esto con el mayor cuidado. Para cada tarjeta:
   • ask: un nuevo ejemplo en el formato exacto del instructor (redacción, tablas, diseño de código, espacios en blanco);
   • read: "Lo que estás viendo": nombra cada parte de la pregunta (plantilla, línea de registros, tablas, etiquetas) y cada símbolo en ella, y di qué pide la pregunta. Escríbelo para alguien que ve este tipo de problema por primera vez;
   • write: su respuesta completa, dispuesta como debe escribirla el estudiante;
   • explain: enseña el concepto adecuadamente: qué es, por qué funciona (el mecanismo), las reglas con razones, un diagrama donde ayude, las trampas y un enlace a la clase o al ejemplo oficial. Apunta a varios párrafos, no a fragmentos con viñetas. Luego haz la pasa de auditoría: para cada problema, pregúntate "¿podría resolverlo un estudiante que solo haya leído las tarjetas de esta unidad?" Si no, añade una tarjeta o mueve el problema. "learn" en units.json puede añadir opcionalmente secciones de notas como lectura de fondo.
3. mock.html (desde templates/mock.html; una fuente tanto para el examen como para la clave). Cada pregunta debe mapearse a un método de unidad del cuaderno de trabajo, y la guía de puntuación mapea cada Parte a la unidad que debe repasarse.
4. master.html (secciones A–J, según la especificación).
5. drill.html (desde templates/drill.html): de 20 a 30 nuevas preguntas ordenadas por probabilidad. Basa la clasificación en lo que el instructor enfatiza (cobertura de problemas de práctica, tiempo de vídeo de repaso, exámenes anteriores) y menciónalo en la introducción. Cada pregunta va seguida inmediatamente de su respuesta: p.look → pre trabajado → p.why. Verifica cada respuesta con código. Las grandes preguntas de la Parte A después de la primera llevan class="qa big" (una página nueva cada una).

Reglas:

• Los problemas son originales (los tipos del instructor, números y código nuevos). Los resúmenes de problemas oficiales están parafraseados, no transcritos.
• Verifica cada respuesta. Calcula cualquier cosa computable con un script Python desechable en el borrador (aritmética, operaciones de bits/hex, desplazamientos, trazas de bucles). Vuelve a leer cada listado de código dado por coherencia.
• Cada solución muestra el trabajo en el formato de mostrar el trabajo de la unidad, y da la respuesta final y una "Trampa:" cuando sea relevante.
• Usa las clases CSS de templates/style.css (.q .qn .lvl.e/.m/.h .work.s/m/l/xl .two .method .showwork .deck .sol .note .warn .good .part .fill .a .exp .keyonly .testonly .pb). No inventes nuevos diseños CSS a menos que sea necesario.

5. Compilar y verificar

• scripts/build.sh <directorio_build> <directorio_materiales>/Study_Pack <CODIGOCURSO> renderiza los seis PDFs con Chrome sin interfaz gráfica y ejecuta check_drill.py (falla si alguna pregunta del cuestionario carece de su respuesta completa) y check_lines.py. Si la verificación de cobertura falla, corrige el contenido (añade la enseñanza/método faltante o re-etiqueta) — nunca elimines la verificación ni etiquetes problemas con métodos que realmente no usan. Corrige las líneas de código marcadas que sean demasiado largas dividiéndolas (cada línea marcada en units/ y wb_*.html debe ser cero) o apilando un bloque .two verticalmente.
• scripts/contact_sheet.sh <pdf> <png> para cada PDF; míralo. Comprueba si hay páginas en blanco o casi vacías, tablas recortadas y claves de respuestas que se filtran en la versión del examen. Amplía una página de solución y una página del simulado a ~70 dpi para confirmar que son legibles.
• Confirma que el PDF del examen no muestra respuestas, y que el PDF de la clave muestra cada respuesta y "Por qué".
• Verifica la respuesta de ejemplo de cada tarjeta con una comprobación Python desechable (diseños, aritmética, trazas), como las soluciones de práctica.
• Lectura de estudiante: renderiza una unidad completa (encabezado → tarjetas → práctica → soluciones) a ~55 dpi y léela en orden, como lo haría el estudiante. Léela como un principiante absoluto: ¿se usa alguna palabra o símbolo antes de ser definido? ¿Cada tarjeta realmente explica? ¿Cada problema se sigue de las tarjetas anteriores?

6. Entregar

• Guarda los PDFs en <directorio_materiales>/Study_Pack/. Envíalos con SendUserFile (cuando esté disponible), con display "attach".
• En la respuesta, proporciona una tabla breve de los seis PDFs (páginas, qué contiene cada uno), el orden recomendado (cuaderno de trabajo Unidad 0 luego unidad por unidad → cuestionario de preguntas y respuestas → repaso mixto → simulado cronometrado → corrige con la clave) y cualquier lugar donde una solución oficial estuviera incompleta o fuera incorrecta.
• Si no pudiste verificar algo (p. ej., contenido de solo audio en un vídeo), indícalo.

Valores predeterminados cuando el usuario no da detalles

• Salida: PDFs tamaño carta; el prefijo del archivo es el código del curso; la carpeta es Study_Pack/ junto a los materiales.
• Simulado: ~1,5–2 veces la duración del examen real, organizado por tipo de pregunta, con puntuación.
• Cuaderno de trabajo: de 8 a 12 problemas por unidad más un repaso mixto de 5 a 8 problemas.
• No preguntes antes de empezar a menos que falten materiales o sean ambiguos (p. ej., dos cursos diferentes en una misma carpeta).