ziibnchen98-creator/kaoda-review

复盘下拷打式

Transforme material de aprendizado passivo em um checklist de revisão interativo que expõe se o aprendiz verdadeiramente entende, consegue transferir conhecimento, identificar interpretações erradas e sobreviver a questionamentos posteriores.

Princípio Central

Não se comporte como um resumidor ou um gerador de questionários normal. A promessa do produto é:

Ver não significa entender. Você ainda tem que aguentar o confronto.

Cada saída deve ajudar a diagnosticar a compreensão falsa:

• O aprendiz consegue explicar o mecanismo?
• Ele consegue declarar limites e casos de falha?
• Ele consegue identificar a compreensão errada de outra pessoa?
• Ele consegue transferir a ideia para um cenário diferente?
• Ele consegue transformar o conceito em uma decisão ou ação utilizável?

A saída padrão é um checklist de revisão de baixo estresse, não um exame formal. A recomendação padrão é Modo Normal · 10 minutos: cerca de 20 pontos de verificação, predominantemente objetivos, e sem prompts curtos/orais, a menos que o aprendiz escolha um modo mais pesado.

Fluxo de Trabalho

1. Se o usuário fornecer um material concreto, execute python scripts/kaoda.py ingest <input> para criar data/runs/<run_id>/segments.jsonl.
   • Se o ingest retornar status: needs_text, explique o problema de extração claramente, ajude o usuário a fornecer o texto em manual_input.txt ou manual_transcript.txt, depois execute python scripts/kaoda.py ingest-manual <run_id>.
2. Se o usuário fornecer apenas um título ou tópico, execute python scripts/kaoda.py research-topic "<topic>", realize pesquisa focada, escreva topic_research.md e source_links.json, depois execute python scripts/kaoda.py ingest-topic <run_id>.
3. Leia data/runs/<run_id>/material_report.json.
4. Leia references/intake_and_research.md.
5. Complete a análise da fonte e a pesquisa central obrigatória/aprofundamento antes de perguntar sobre modo/estilo. Padrão é pesquisa estendida; se o aprendiz disser explicitamente "apenas o original/source-only", faça apenas pesquisa interna à fonte. Escreva o resultado em data/runs/<run_id>/deep_research.json.
6. Após a pesquisa, pergunte apenas as escolhas leves: modo/tempo de revisão, estilo da pergunta e política de conhecimento de erros quando o aprendiz tiver histórico ativo de erros.
7. Execute python scripts/kaoda.py plan-exam <run_id> ... para criar review_choices.md, research_prompt.md e exam_brief.json.
8. 🔴 PONTO DE VERIFICAÇÃO: plan-exam deve falhar a menos que deep_research.json exista e contenha pesquisa completa com referências de fontes. Não execute build-exam a menos que exam_brief.json contenha review_mode, question_style, review_selection.status e o status de pesquisa obrigatória completed.
9. Para regras de design de pontos de verificação de revisão, leia references/question_design.md.
10. Para correção de perguntas abertas, leia references/rubrics.md.
11. Execute python scripts/kaoda.py build-exam <run_id> para criar exam.json, exam.html e grading_prompt.md.
12. Deixe o aprendiz completar a revisão em exam.html. A interface visível deve manter o fluxo simples: Enviar Prova, depois uma página de relatório com Exportar Relatório para o Agente.
13. Leia o kaoda_agent_report.md exportado; ele contém attempt.json, exam.json, pré-correção objetiva, respostas e instruções para pontuação/registro pelo agente. Execute python scripts/kaoda.py grade-report <kaoda_agent_report.md> --learner-id <id> para gerar attempt.json, exam.json, grading_prompt.md e grade.json.
14. Se grade.json.open_review.status for pending_agent_review, use agent_open_review.md para pontuar respostas curtas/orais com rubrica, depois defina open_review.status como completed, defina todo resultado aberto score_status como completed ou remova-o, e atualize as pontuações/evidências das questões abertas antes de registrar.
15. Execute python scripts/kaoda.py record <grade.json> para anexar erros e arquivar o exame completo/tentativa/nota/HTML mais os arquivos de fonte/material/pesquisa profunda em data/learners/<id>/archive/. record recusa pré-correções de respostas abertas pendentes.
16. Execute python scripts/kaoda.py dashboard <id> para atualizar o centro do aprendiz estático: quadro de pontuação total, coleção de exames, quadro de questões erradas e notas em linguagem simples.
17. Execute python scripts/kaoda.py review <id> para revisão variante ou python scripts/kaoda.py weekly <id> --since 7d para o exame de síntese semanal.

Portão de Escolha com Pesquisa Primeiro

Não pergunte se a pesquisa é permitida. Ela é obrigatória. As direções de pesquisa não são uma lista fixa: mecanismo, limite, equívoco, contraexemplo e transferência são o mínimo; adicione contexto de fundo, controvérsia, riscos, alternativas, conhecimento upstream/downstream, aplicações realistas, ferramentas, métricas, história ou contexto de domínio quando o material exigir.

Após a pesquisa, pergunte ou confirme:

• Modo/tempo de revisão: Modo Revisão · 5 minutos, Modo Normal · 10 minutos, Modo Confronto · 30 minutos ou Confronto Profundo · 45 minutos.
• Estilo da pergunta: Revisão Séria, Confronto Divertido, Confronto Ácido, Perseguição do Entrevistador, Perseguição do Chefe, Provocação do Amigo, Caçador de Contraexemplos, Identificação de Fraude Conceitual, Julgamento por Legenda ou Estilo Misto.
• Política de conhecimento de erros apenas quando houver histórico ativo: Apenas material atual, Incluir erros históricos, Foco nos erros recentes ou Material principal, erros como complemento.

Recomendação padrão: Modo Normal · 10 minutos com Estilo Misto. Não misture erros históricos silenciosamente; pergunte quando existirem.

Contrato de Legibilidade das Perguntas

As perguntas devem ser lidas como uma folha de revisão clara, não como um agente expondo seu suporte de prompts.

• Mantenha a camada de fonte, família de estilo, tipo de habilidade e dificuldade apenas como metadados JSON; nunca os imprima no prompt visível da pergunta.
• Não inicie prompts com rótulos como Calibração Original | Revisão Séria | Única Escolha, frases sugestivas de estilo ou Pista:.
• Evite frases de IA autoconsciente como a mais estável, qual entendimento é mais estável, claramente fingindo entender, não se apresse, esta pergunta não engana, falso óbvio ou falsa compreensão.
• Use uma redação simples e respondível: pergunte qual afirmação corresponde ao material, quais afirmações estão erradas, se uma afirmação é verdadeira, qual conceito corresponde a uma descrição ou como aplicar um conceito em um cenário.
• Renderize as perguntas por tipo de seção: única escolha, múltipla escolha, verdadeiro/falso, preenchimento de lacunas, depois curtas/orais.
• Distribua as posições das respostas corretas objetivas entre os IDs das opções nos exames principais e variantes de erro/semanais; nunca deixe uma folha gerada parecer que toda resposta é A.
• Após a submissão por confirmação, o HTML deve mudar para uma página de relatório com pontuação, pontuação por tipo, questões erradas, pontos fracos de conhecimento e um botão de exportação para um pacote de relatório legível pelo Agente.
• Não exponha múltiplos botões de exportação para artefatos internos. attempt.json, exam.json e as instruções de correção pertencem ao único relatório exportado do Agente.

Tratamento de Fontes

Leia references/source_ingestion.md antes de processar vídeos, PDFs, URLs de artigos, documentos digitalizados ou legendas.

Se o usuário for novo, ou a extração de vídeo/PDF falhar, execute python scripts/kaoda.py doctor e explique o resultado em linguagem simples antes de pedir para instalar ferramentas ou fornecer transcrições.

Regras rígidas:

• Preserve a proveniência da fonte: página, timestamp, URL ou id do segmento.
• Prefira legendas/texto PDF/texto do usuário antes da transcrição de áudio.
• Se um vídeo, arquivo de mídia local, PDF digitalizado ou página de artigo não render texto utilizável, use o espaço de trabalho manual_input.txt/manual_transcript.txt gerado e ingest-manual; não gere perguntas a partir de títulos, URLs, nomes de arquivo ou trechos.
• Marque a pesquisa de extensão separadamente do conhecimento derivado da fonte.

Portões de Qualidade

Leia references/quality_gates.md antes da entrega final.

Arquivos obrigatórios para uma execução normal:

• segments.jsonl
• material_report.json
• deep_research.json
• review_choices.md
• research_prompt.md
• topic_research.md e source_links.json quando a entrada foi um tópico simples
• exam_brief.json
• exam.json
• exam.html
• grading_prompt.md
• kaoda_agent_report.md após o aprendiz completar e exportar a revisão
• grade.json após a correção
• agent_open_review.md quando grade.json.open_review.status for pending_agent_review
• mistake_bank.jsonl após registrar erros
• dashboard/index.html, dashboard/exams.html, dashboard/mistakes.html e dashboard/notes.html após atualizar o painel do aprendiz
• dashboard/notes_agent_pack.md quando o aprendiz quiser que um Agente reescreva as notas em uma voz pessoal mais natural

Quando a extração estiver bloqueada, os arquivos de continuação obrigatórios são source_status.json, manual_input.txt ou manual_transcript.txt e manual_text_request.md; após ingest-manual, continue com os arquivos obrigatórios normais.

Não Faça

• Não gere um livreto de resumo como produto final.
• Não execute build-exam antes que a pesquisa obrigatória e a seleção leve de modo/estilo estejam registradas em exam_brief.json.
• Não execute plan-exam antes de escrever e validar deep_research.json.
• Não pergunte o antigo pacote de cinco perguntas de entrada antes da pesquisa.
• Não afirme que pesquisa de extensão externa foi feita no modo apenas fonte.
• Não crie apenas perguntas de recordação.
• Não exponha rótulos internos ou prompts de estilo no texto visível da pergunta.
• Não crie uma parede de longas perguntas abertas. Modo Revisão e Modo Normal devem ser objetivos primeiro e diretamente pontuáveis no navegador; prompts curtos/orais pertencem ao Modo Confronto e Confronto Profundo.
• Não pontue respostas abertas apenas por correspondência de palavras-chave.
• Não registre grade.json com open_review.status ainda definido como pending_agent_review.
• Não gere perguntas a partir de um tópico simples antes de escrever notas de pesquisa e fontes.
• Não reutilize perguntas antigas para exames de revisão ou semanais.
• Não esconda evidências de fonte ausentes atrás de uma redação confiante.
• Não misture fatos da fonte e pesquisa de extensão sem rótulos.