ziibnchen98-creator/kaoda-review

拷打式复盘 (Revisión Interrogativa)

Convierte material de aprendizaje pasivo en una lista de verificación interactiva que expone si el alumno realmente comprende, puede transferir, identificar interpretaciones erróneas y resistir preguntas de seguimiento.

Principio Fundamental

No actúes como un resumidor o un generador de cuestionarios normal. La promesa del producto es:

Verlo no significa que lo entiendas. Tienes que aguantar el interrogatorio.

Cada salida debe ayudar a diagnosticar la comprensión falsa:

• ¿Puede el alumno explicar el mecanismo?
• ¿Puede enunciar los límites y casos de fallo?
• ¿Puede identificar la comprensión errónea de otra persona?
• ¿Puede transferir la idea a un escenario diferente?
• ¿Puede convertir el concepto en una decisión o acción utilizable?

La salida predeterminada es una lista de verificación de revisión de bajo riesgo, no un examen formal. La recomendación predeterminada es Modo Normal · 10 minutos: alrededor de 20 puntos de control, principalmente objetivos, y sin preguntas cortas/orales a menos que el alumno elija un modo más intensivo.

Flujo de Trabajo

1. Si el usuario proporciona un material concreto, ejecuta python scripts/kaoda.py ingest <input> para crear data/runs/<run_id>/segments.jsonl.
   • Si ingest devuelve status: needs_text, explica claramente el problema de extracción, ayuda al usuario a proporcionar texto en manual_input.txt o manual_transcript.txt, luego ejecuta python scripts/kaoda.py ingest-manual <run_id>.
2. Si el usuario solo da un título o tema, ejecuta python scripts/kaoda.py research-topic "<topic>", realiza una investigación enfocada, escribe topic_research.md y source_links.json, luego ejecuta python scripts/kaoda.py ingest-topic <run_id>.
3. Lee data/runs/<run_id>/material_report.json.
4. Lee references/intake_and_research.md.
5. Completa el análisis de la fuente y la investigación central obligatoria/profundización antes de preguntar sobre el modo/estilo. Por defecto, investiga extendidamente; si el alumno dice explícitamente "solo la fuente/original", haz solo investigación interna de la fuente. Escribe el resultado en data/runs/<run_id>/deep_research.json.
6. Después de la investigación, pregunta solo las elecciones ligeras: modo/tiempo de revisión, estilo de preguntas y política de errores-conocimiento cuando el alumno tenga un historial activo de errores.
7. Ejecuta python scripts/kaoda.py plan-exam <run_id> ... para crear review_choices.md, research_prompt.md y exam_brief.json.
8. 🔴 PUNTO DE CONTROL: plan-exam debe fallar a menos que deep_research.json exista y contenga investigación completada con referencias de fuentes. No ejecutes build-exam a menos que exam_brief.json contenga review_mode, question_style, review_selection.status y el estado de investigación obligatoria completed.
9. Para las reglas de diseño de puntos de control de revisión, lee references/question_design.md.
10. Para la calificación de respuestas abiertas, lee references/rubrics.md.
11. Ejecuta python scripts/kaoda.py build-exam <run_id> para crear exam.json, exam.html y grading_prompt.md.
12. Deja que el alumno complete la revisión en exam.html. La interfaz de usuario visible debe mantener el flujo simple: Enviar examen, luego una página de informe con Exportar informe al agente.
13. Lee el kaoda_agent_report.md exportado; contiene attempt.json, exam.json, precalificación objetiva, respuestas e instrucciones para la calificación/registro del agente. Ejecuta python scripts/kaoda.py grade-report <kaoda_agent_report.md> --learner-id <id> para generar attempt.json, exam.json, grading_prompt.md y grade.json.
14. Si grade.json.open_review.status es pending_agent_review, usa agent_open_review.md para calificar con rúbrica las respuestas cortas/orales, luego establece open_review.status en completed, establece cada resultado abierto score_status en completed o elimínalo, y actualiza las puntuaciones/evidencia de preguntas abiertas antes de registrar.
15. Ejecuta python scripts/kaoda.py record <grade.json> para agregar errores y archivar el examen/intento/calificación/HTML completo más los archivos de fuente/material/investigación profunda en data/learners/<id>/archive/. record rechaza precalificaciones de respuestas abiertas pendientes.
16. Ejecuta python scripts/kaoda.py dashboard <id> para actualizar el centro de aprendizaje estático: tabla de puntuaciones totales, colección de exámenes, tablero de preguntas incorrectas y notas en lenguaje sencillo.
17. Ejecuta python scripts/kaoda.py review <id> para revisión variante o python scripts/kaoda.py weekly <id> --since 7d para el examen semanal de síntesis.

Puerta de Elección Basada en Investigación

No preguntes si se permite la investigación. Es obligatoria. Las direcciones de investigación no son una lista de verificación fija: mecanismo, límite, concepto erróneo, contraejemplo y transferencia son el mínimo; agrega contexto, controversia, riesgos, alternativas, conocimiento aguas arriba/abajo, aplicaciones realistas, herramientas, métricas, historia o contexto de dominio cuando el material lo requiera.

Después de la investigación, pregunta o confirma:

• Modo/tiempo de revisión: Modo Repaso · 5 minutos, Modo Normal · 10 minutos, Modo Interrogatorio · 30 minutos o Interrogatorio Profundo · 45 minutos.
• Estilo de preguntas: Repaso serio, Interrogatorio divertido, Interrogatorio sarcástico, Preguntas del entrevistador, Preguntas del jefe, Crítica del amigo, Cazador de contraejemplos, Detección de engaños conceptuales, Juicio de comentarios o Estilo mixto.
• Política de errores-conocimiento solo cuando exista historial activo: Solo revisar el material actual, Agregar errores históricos, Interrogar principalmente los errores recientes o Priorizar el material actual, errores como secundarios.

Recomendación predeterminada: Modo Normal · 10 minutos con Estilo mixto. No combines silenciosamente errores históricos; pregunta cuando existan.

Contrato de Legibilidad de Preguntas

Las preguntas deben leerse como una hoja de revisión clara, no como un agente exponiendo su andamiaje de instrucciones.

• Mantén la capa de fuente, la familia de estilo, el tipo de habilidad y la dificultad solo como metadatos JSON; nunca los imprimas en la pregunta visible.
• No prefijes las preguntas con etiquetas como Calibración de fuente｜Repaso serio｜Opción única, frases de pista de estilo o Pista:.
• Evita frases autoconcientes de IA como la más estable, qué entendimiento es más estable, claramente está fingiendo, no te apresures, esta pregunta no engaña, falso a primera vista o pseudo-comprensión.
• Usa redacción simple y respondible: pregunta qué afirmación se ajusta al material, qué afirmaciones son incorrectas, si una afirmación es verdadera, qué concepto coincide con una descripción, o cómo aplicar un concepto en un escenario.
• Renderiza las preguntas por sección de tipo: opción única, opción múltiple, verdadero/falso, completar, luego corta/oral.
• Distribuye las posiciones de respuestas correctas objetivas entre los IDs de opciones en exámenes principales y variantes de errores/semanales; nunca permitas que una hoja generada parezca que todas las respuestas son A.
• Después del envío basado en confirmación, el HTML debe cambiar a una página de informe con puntuación, puntuación por tipo, preguntas incorrectas, puntos débiles de conocimiento y un botón de exportación para un paquete de informe legible por el agente.
• No expongas múltiples botones de exportación para artefactos internos. attempt.json, exam.json y las instrucciones de calificación deben estar dentro del único informe de agente exportado.

Manejo de Fuentes

Lee references/source_ingestion.md antes de procesar videos, PDFs, URLs de artículos, documentos escaneados o subtítulos.

Si el usuario es nuevo, o la extracción de video/PDF falla, ejecuta python scripts/kaoda.py doctor y explica el resultado en lenguaje sencillo antes de pedirle que instale herramientas o proporcione transcripciones.

Reglas estrictas:

• Preserva la procedencia de la fuente: página, marca de tiempo, URL o ID de segmento.
• Prefiere subtítulos/texto de PDF/texto de usuario antes que transcripción de audio.
• Si un video, archivo multimedia local, PDF escaneado o página de artículo no puede producir texto utilizable, usa el espacio de trabajo manual_input.txt/manual_transcript.txt generado y ingest-manual; no generes preguntas a partir de títulos, URLs, nombres de archivo o fragmentos.
• Marca la investigación de extensión por separado del conocimiento derivado de la fuente.

Controles de Calidad

Lee references/quality_gates.md antes de la entrega final.

Archivos requeridos para una ejecución normal:

• segments.jsonl
• material_report.json
• deep_research.json
• review_choices.md
• research_prompt.md
• topic_research.md y source_links.json cuando la entrada fue un tema simple
• exam_brief.json
• exam.json
• exam.html
• grading_prompt.md
• kaoda_agent_report.md después de que el alumno complete y exporte la revisión
• grade.json después de la calificación
• agent_open_review.md cuando grade.json.open_review.status sea pending_agent_review
• mistake_bank.jsonl después de registrar errores
• dashboard/index.html, dashboard/exams.html, dashboard/mistakes.html y dashboard/notes.html después de actualizar el panel del alumno
• dashboard/notes_agent_pack.md cuando el alumno quiera que un agente reescriba las notas en un tono personal más natural

Cuando la extracción está bloqueada, los archivos de continuación requeridos son source_status.json, manual_input.txt o manual_transcript.txt, y manual_text_request.md; después de ingest-manual, continúa con los archivos requeridos normales.

No Hacer

• No generes un folleto de resumen como producto final.
• No ejecutes build-exam antes de que la investigación obligatoria y la selección ligera de modo/estilo estén registradas en exam_brief.json.
• No ejecutes plan-exam antes de escribir y validar deep_research.json.
• No preguntes el antiguo paquete de cinco preguntas de ingesta antes de la investigación.
• No afirmes que se realizó investigación de extensión externa en modo solo fuente.
• No crees solo preguntas de recuerdo.
• No expongas etiquetas internas o indicaciones de estilo en el texto visible de las preguntas.
• No crees un muro de preguntas largas de respuesta abierta. Modo Repaso y Modo Normal deben ser principalmente objetivos y directamente calificables en el navegador; las preguntas cortas/orales pertenecen a Modo Interrogatorio e Interrogatorio Profundo.
• No califiques respuestas abiertas solo con coincidencia de palabras clave.
• No registres grade.json con open_review.status todavía en pending_agent_review.
• No generes preguntas a partir de un tema simple antes de escribir notas de investigación del tema y fuentes.
• No reutilices preguntas antiguas para exámenes de revisión o semanales.
• No ocultes la evidencia de fuente faltante detrás de un lenguaje confiado.
• No mezcles hechos de fuente e investigación de extensión sin etiquetas.