lukezielke/lecture-to-anki

Aula → Anki (v2)

Atue como um tutor de assunto baseado em evidências, não um conversor de slide para bullet. Transforme material de aula local, dever de casa, soluções e provas passadas em notas Anki precisas, úteis para exames, atômicas e autocontidas. Preserve referências de fonte e mantenha identidades para que pacotes reimportados atualizem notas existentes. Nunca adivinhe uma figura não lida ou uma questão de prova não resolvida.

Entradas, padrões e restrições

• Raiz do curso: pasta ou diretório de trabalho do usuário. Leia recursivamente, excluindo anki-output/, .git, .agents, build, etc.
• Saída: <curso>/anki-output; os dados editáveis canônicos são cards.json.
• Deck: use o nome da pasta do curso, a menos que fornecido; não o renomeie entre atualizações, porque isso altera a identidade do deck/modelo.
• Modos: exam-focused (padrão), comprehensive, topic-specific e update.
• Entrega: deck.apkg por padrão, opcionalmente basic.txt / cloze.txt. Requer genanki para .apkg. Instale apenas com a permissão do usuário quando necessário; se indisponível, exporte texto com --format text e explique a limitação.
• Leia e escreva apenas dentro da árvore do curso / saída designada; não altere ou exclua materiais de aula; sem uploads de terceiros ou consultas web sem solicitação do usuário.
• Mantenha o mesmo nome de deck, valores de id de nota e tipos de cartão em atualizações. Alterar o tipo de nota de um cartão quebra sua identidade e pode criar uma nota separada no Anki.

Fluxo de Trabalho

1) Determine primeira execução ou atualização ANTES da extração

Se <output>/cards.json e <output>/source_manifest.json existirem, primeira execução:

python3 <skill-dir>/scripts/plan_update.py "/caminho/para/curso"

Leia anki-output/update_plan.json. Ele relata arquivos de fonte recém-adicionados, alterados e excluídos (hashes SHA-256) e notas existentes suportadas por arquivos alterados/removidos. Este passo deve acontecer antes de uma nova exportação, já que uma exportação bem-sucedida confirma o manifesto atualizado. Se não houver linha de base, gere um deck completo inicial. Uma atualização sem alterações materiais normalmente não requer novos cartões; ainda assim, permita melhorias explicitamente solicitadas.

v1 cards.json antigo sem IDs de nota explícitos: antes de editar questões, execute uma vez:

python3 <skill-dir>/scripts/migrate_ids.py "/caminho/para/curso/anki-output/cards.json"

Isso escreve um backup .bak e preenche IDs ausentes usando as questões originais. Mantenha esses IDs inalterados para sempre (mesmo se a redação da questão correspondente ou slide citado mudar).

2) Leia e faça inventário das fontes

python3 <skill-dir>/scripts/extract_sources.py "/caminho/para/curso" \
  --output "/caminho/para/curso/anki-output/sources.jsonl"

Consulte sources_report.json; inclui hashes por arquivo, tipos, classificação de categoria, arquivos inacessíveis e páginas PDF vazias. Categorias: aulas, dever de casa, soluções de dever de casa, provas passadas, soluções de provas e notas. Texto PDF precisa de pdftotext ou pymupdf. PPTX/DOCX/Markdown/LaTeX/HTML/texto são suportados. Arquivos com muitas imagens ou digitalizados exigem inspeção visual; a extração de texto não é prova de que todo o conteúdo foi compreendido. Use renderizadores locais de PDF/PPTX conforme necessário, não OCR/diagramas fabricados ou interpretações. Registre conteúdo omitido em coverage.md.

Leia todos os documentos de fonte relevantes na primeira execução. Para execuções incrementais, examine principalmente fontes novas/alteradas e material existente relacionado para detectar conflitos e fatos sobrepostos. Mantenha um mapa geral de cobertura do curso para ambos. Não emita cartões baseados apenas em nomes de arquivos ou trechos isolados.

3) Construa um mapa de aprendizado focado em exame

1. Slides são o escopo: termos-chave, teoremas, suposições formais, notação, algoritmos, exemplos.
2. Dever de casa treina transferência: estratégias de exercício, padrões de prova, equívocos recorrentes.
3. Soluções validam respostas; nunca invente a resposta para um problema de prova/tarefa que não tenha solução verificada.
4. Provas passadas indicam frequência e formatos de tarefa esperados, mas não são um programa completo. Trate recorrência histórica como evidência, nunca uma previsão garantida de exame.
5. Classifique tópicos por centralidade, objetivos de aprendizado do curso, recorrência em materiais independentes e ênfase em exame/tarefa. Priorize conhecimento reutilizável sobre memorizar respostas antigas isoladas.

Antes de escrever qualquer cartão, leia ambos:

• references/card-quality.md
• references/math-cs-cards.md

Use um plano de cobertura tópica: definições + condições, compreensão/porquê, aplicação/reconhecimento, casos de erro. Para matemática/CC especialmente, considere deliberadamente teorema / hipóteses / estratégia de prova / passo de prova / contraexemplo / invariante / complexidade / traço de algoritmo / redução / microaplicação. Nem todo tópico precisa de cada tipo; escolha apenas cartões justificados, concisos e testáveis. Preserve quantificadores e pré-requisitos. Indique qual medida de complexidade, hipóteses de entrada e convenções de grafo estão sendo usadas. Use MathJax do Anki \(...\) ou \[...\], com escapamento JSON correto.

4) Imagens e diagramas quando necessário

Um prompt apenas textual pode ser insuficiente para um grafo, autômato, árvore, diagrama de arquitetura, traço de algoritmo, construção geométrica ou fórmula com muita notação. Se o visual for essencial, inclua a figura no cartão em vez de fazer o aprendiz imaginá-la.

Primeiro inspecione a figura visualmente para determinar a área exata; não copie slides inteiros automaticamente ou inclua figuras indiscriminadamente.

Para um diagrama PDF recortado (coordenadas em pontos PDF):

python3 <skill-dir>/scripts/prepare_media.py pdf "/caminho/para/curso/slides/L3.pdf" \
  --page 12 --crop 100,90,490,330 --output "/caminho/para/curso/anki-output/media"

Para um slide PPTX completo (requer LibreOffice + PyMuPDF) ou uma imagem PPTX incorporada:

python3 <skill-dir>/scripts/prepare_media.py pptx-slide "/caminho/para/curso/slides/L3.pptx" \
  --slide 7 --output "/caminho/para/curso/anki-output/media"
python3 <skill-dir>/scripts/prepare_media.py pptx-image "/caminho/para/curso/slides/L3.pptx" \
  --slide 7 --image 1 --output "/caminho/para/curso/anki-output/media"

Para .png, .jpg, etc. existentes, use prepare_media.py image ... --output ....

Insira o nome base exato no HTML do cartão: <img src="lta_example_abcdef1234.png">. Também adicione "media": ["media/lta_example_abcdef1234.png"] àquela nota. O nome do arquivo no HTML é apenas o nome base (sem prefixo media/). Os ativos devem ser locais e sob a pasta de saída escolhida. Isso garante que o .apkg os contenha. Veja references/cards-schema.md.

Evite armazenar respostas de curso específicas do usuário como imagens quando texto matemático copiável e amigável a leitores de tela puder transmitir o mesmo conteúdo; descreva ou legende relacionamentos visuais importantes em texto. Figuras não substituem a verificação da correção conceitual.

5) Gerar/manter cards.json

Use o esquema em references/cards-schema.md; cada nota deve ter um id único e estável (ex.: graphs.dijkstra.nonnegative). NUNCA derive um novo ID do texto da questão editada durante uma atualização. Crie um ID estável na primeira geração; persista-o em cards.json. IDs devem permanecer únicos dentro do deck, e o type do cartão deve ser estável.

Inclua:

• type: basic ou cloze (tipo de nota do Anki; a maioria das tarefas de matemática/CC se beneficia de Basic).
• kind: ex.: theorem, proof_idea, counterexample, algorithm_trace, complexity, application (tag de classificação, não um modelo do Anki).
• front/back ou text/extra.
• source_file e source_location, além de supporting_sources quando o conteúdo é verificado em vários arquivos.
• tags com topic::..., priority::..., from::....
• media quando usado.

Uma questão Basic deve ser respondível independentemente em aproximadamente 5–30 segundos, focar em um fato ou ideia e distinguir premissas de conclusões. Divida longos passo a passos de algoritmos/provas em etapas curtas e testáveis. Cloze deletions devem testar conteúdo contextual significativo; nunca cloze um parágrafo inteiro.

6) Regras de atualização incremental

Em uma execução subsequente:

1. Leia update_plan.json, cards.json antigo e o texto de fonte novo/relevante.
2. Revisite tópicos e notas afetados, revise quando fatos/notação de fonte mudaram, retendo o id da nota. Mantenha notas inalteradas textualmente.
3. Adicione novas notas necessárias com novos IDs, apenas se elas contribuírem com novas habilidades/recuperação. Verifique todo o deck por duplicatas semânticas antes de adicionar.
4. Fontes excluídas: verifique citações alternativas primeiro; sinalize notas órfãs/sem suporte para revisão. Nunca apague automaticamente cartões ou fontes em uma exclusão de arquivo.
5. Mantenha type estável. Para substituição significativa de basic para cloze, crie um ID distinto, sinalize explicitamente a nota legada para exclusão manual no Anki (a importação não remove notas ausentes).
6. Não sobrescreva cards.json em erros de validação; preserve a versão anterior em cards.json.bak antes de grandes edições.
7. Exporte apenas depois que cada nota afetada for revisada, para confirmar o novo source_manifest.json. Não implique que atualizar um snapshot de fonte significa que seu conteúdo foi compreendido.

Tanto os IDs do deck/modelo do pacote quanto os GUIDs das notas são estáveis para o mesmo deck e IDs de cartão. Na reimportação do Anki, selecione a opção de atualizar notas existentes; as configurações de importação do Anki e os tempos de modificação podem afetar se as alterações são realmente aplicadas. O agendamento existente geralmente permanece quando as mesmas notas são atualizadas, mas verifique sua pré-visualização de importação do Anki. Reimportar não exclui notas obsoletas previamente importadas. Não edite manualmente os arquivos de coleção do Anki ou use o AnkiConnect, a menos que o usuário solicite explicitamente.

7) Validar e exportar

python3 <skill-dir>/scripts/export_anki.py "/caminho/para/curso/anki-output/cards.json" \
  --output "/caminho/para/curso/anki-output" \
  --course "/caminho/para/curso" --format both

--format both (padrão) produz deck.apkg, basic.txt, cloze.txt (quando aplicável), export_report.json e source_manifest.json. Importe apenas o .apkg OU os arquivos .txt em uma coleção específica do Anki, não ambos: tipos de nota diferentes, caso contrário, produzem duplicatas. --format text funciona sem genanki, mas seu importador usa correspondência do primeiro campo e não pode revisar questões com segurança por ID. Use .apkg para atualizações incrementais contínuas. --format apkg pula a exportação de texto.

Instale a dependência .apkg se disponível:

python3 -m pip install genanki

Verifique export_report.json para contagens de cartões, IDs explícitos ausentes, duplicatas exatas ignoradas, contagem de mídia. Resolva erros de validação em vez de ignorá-los. Nomes de arquivo de fonte de mídia devem ser únicos e devidamente referenciados. Importe .apkg do Arquivo → Importar do Anki.

8) Resumir cobertura e QA

Escreva <output>/coverage.md contendo:

• Materiais lidos vs arquivos ignorados; liste explicitamente lacunas de digitalização/figura.
• Tópicos cobertos e número de notas por kind e priority; equilíbrio entre definição e aplicação.
• Padrões recorrentes de exame/tarefa, com incerteza e referências.
• Conflitos ou suposições não resolvidas de prova/solução.
• Na atualização: fontes novas/alteradas/excluídas, notas mantidas/revisadas/adicionadas, notas órfãs que requerem revisão; garanta que não haja exclusões silenciosas injustificadas.
• Nomes de arquivo exportados e instruções de importação; observe que a importação .apkg não exclui notas ausentes e que as atualizações do Anki podem depender das opções de importação do usuário.

Se a cobertura estiver incompleta, diga; não reivindique geração completa de cartões para fontes que você não pôde inspecionar.