adamaiken89/aprender-algo

Framework Aprender Algo

Transforme um assunto em um currículo estruturado por meio de uma sessão interativa com LLM. Estude via CLI: leia aulas, explique de volta, faça perguntas de múltipla escolha (MCQs) e pratique com repetição espaçada.

1. Pedagogia

Três teorias fundidas:

Teoria	Papel da IA	Problema resolvido
Marva Collins	Tutor socrático. Perguntas e respostas rigorosas, altas expectativas, paciência infinita	Precisa de um grande professor. A IA nunca se cansa.
Técnica Feynman	Detector de lacunas. O aluno explica de forma simples → a IA encontra falhas	Ilusão de compreensão
Dificuldades Desejáveis	Agendador espaçado. Recuperação FSRS + prática intercalada	Releitura passiva

Mapeamento Fase da Sessão → Teoria

Fase	Teoria	Aluno	IA/CLI
Ler	Marva	Estudar a aula	Escrever conteúdo claro
Explicar	Feynman	Explicar o conceito de forma simples	Questionar: "você disse X, mas Y — reconcilie"
Praticar	Marva + Desejável	Responder MCQs, justificar	Avaliar, explicar distratores
Julgar	Marva	Criticar, formar opinião	Acompanhamento socrático
Revisar	Desejável	Recordação ativa via FSRS	Agendar intervalos ideais

Orçamento de Tempo

• Assunto: Máx. 40h (13 sem × 3h/sem)
• Módulo: 1,5-3h, ~15-20 por assunto
• Revisão SRS: ~10-15 min diários

2. Estrutura de Conteúdo

<topico>/
├── syllabus.yaml             # Especificação do curso
├── modules/
│   ├── NN-nome/
│   │   ├── lesson.md         # Conteúdo principal + exercícios
│   │   ├── quiz.yaml         # 8-10 MCQs
│   │   └── cloze.yaml        # 8-10 perguntas cloze
│   └── ...
└── srs/
    ├── deck.json             # Cartões FSRS-5
    └── stats.json            # Histórico

Modelos completos em templates/. Chave: syllabus.yaml (esqueleto de 20 módulos), module.md (estrutura da aula), quiz.yaml (formato MCQ com 4 opções).

3. Protocolo de Criação de Conteúdo

Fluxo de Trabalho

1. Escopo (5 min): Perguntar domínio/nível/orçamento de tempo/idioma/caso de uso. Propor syllabus.
2. Fase de esboço: Verificar DAG de módulos + cadeia de pré-requisitos. Verificar orçamento de tempo.
3. Por módulo (10 min): Criar módulo com learn.sh create-module <topico> NN-nome. Número de dois dígitos com zero à esquerda + nome em kebab-case (ex.: 01-intro, 02-conceitos-base). Escrever lesson.md + quiz.yaml. Aplicar as 16 regras de qualidade em linha. Manter lesson.md ≤12.000 caracteres. Se o conteúdo transbordar, dividir em módulos adicionais e atualizar o syllabus. O usuário revisa. Prosseguir. 3.5. Validar sintaxe: Executar learn.sh validate-content <topico> [modulo]. Corrigir todos os erros de markdown + mermaid antes de prosseguir.
4. Pré-publicação: Carregar content-verify.md. Executar lista de verificação. Corrigir violações.
5. Compilar SRS (2 min): Extrair MCQs → baralho FSRS-5.
6. Quizzes cumulativos: A cada 3-5 módulos, gerar cumulative_quiz.yaml na raiz do assunto. 8-10 questões misturando cloze, MCQ, V/F. Cada uma marcada com source_modules. Respostas distribuídas entre A-D.

Princípios de Conteúdo

• Alinhamento CILO: Cada módulo atende a ≥1 objetivo de aprendizado. Sem conteúdo supérfluo.
• Idioma: Todo o conteúdo no idioma do syllabus.yaml (en/zh/yue).
• Prático primeiro: Começar com um exemplo concreto antes da definição abstrata.
• Relevante ao domínio: Cenários da indústria do aluno.
• Lacunas cloze: Cada módulo recebe de 3 a 5 lacunas ({termo}). O aluno preenche antes de prosseguir. Força a recuperação durante a leitura.
• Prever o próximo: Cada cadeia causal recebe de 2 a 3 blocos de previsão. O aluno se compromete com o resultado antes da revelação.
• Detecção de erros: Cada módulo recebe de 1 a 2 exercícios "Encontre o Erro". Aprendizagem baseada em erros desenvolve habilidades de diagnóstico.
• Codificação dupla: Cada conceito recebe um diagrama (Mermaid, ascii ou hierarquia estruturada).
• Diversidade de MCQ: 40% memorização, 40% aplicação, 20% multi-etapas.
• Prompt Feynman: Toda aula termina com tarefa de explicação + sonda de lacuna da IA.
• Dificuldade desejável: Mesmo conceito testado de ângulos diferentes entre os módulos.
• Orçamento de tempo: Módulo ≤3h. Assunto ≤40h.
• Limite de tamanho do módulo: Cada lesson.md de módulo ≤12.000 caracteres. Excedeu o limite? Divida o tópico em mais módulos. Ajuste a contagem de módulos do syllabus de acordo.
• Progressão: Baseie-se em pré-requisitos. Módulos anteriores são fundamentais.
• Pular permitido: O aluno fornece entrada esparsa? Gere o conteúdo mesmo assim com padrões sensatos. Não bloqueie.
• Socrático em todo lugar: Cada conceito importante é seguido por uma pergunta que faz o aluno parar e pensar — não apenas no final do módulo, mas em linha após cada nova ideia. Pergunta → breve resposta/explicação imediatamente após para que o aluno possa se autoavaliar. Padrão: declare o conceito → pergunte "por quê?" ou "e se?" → responda.
• Diagramas Mermaid: Para conceitos com lógica de ramificação, máquinas de estado, fluxos de trabalho ou cadeias causais: gere fluxograma Mermaid / diagrama de sequência / diagrama de estado. O tema injeta automaticamente neutral para compatibilidade com tema escuro/claro. Use paleta de cores terrosas suaves para preenchimentos style — visível em temas escuros e claros. Paleta: azul #5c7a99, verde #5c8a6a, laranja #b8924a, vermelho #b86a4a, roxo #7a5a8a, cinza #888. Traços: use tom mais escuro do preenchimento ou #333. Exemplo: style A fill:#5c7a99,stroke:#333. Colocar após a explicação do conceito, antes da pergunta Pense.
• Mapa mental do módulo: Cada módulo recebe um mapa mental Mermaid no topo do lesson.md (após os metadados, antes dos Objetivos de Aprendizagem). Mostra a hierarquia do conhecimento: conceito central → tópicos principais → subconceitos. Use sintaxe mindmap. Máximo de 3 níveis de profundidade.
• Distribuição de respostas: As chaves de resposta MCQ devem ser distribuídas entre A/B/C/D. Nenhuma sequência de mais de 2 questões consecutivas pode compartilhar a mesma letra de resposta. O modelo mostra B como exemplo — gire durante a geração.
• Quizzes cumulativos: A cada 3-5 módulos, gere cumulative_quiz.yaml na raiz do assunto. 8-10 questões misturando cloze, MCQ, V/F. Cada questão marcada com source_modules. Respostas distribuídas entre A-D.

Regras de Qualidade de Conteúdo (16)

#	Regra	O que fazer	Exemplo ruim → Exemplo bom
1	Explique convenções	Explique por que a convenção existe, não apenas o que ela é	"Preço cotado 95" → "95 = 95% do valor de face de $1.000. A convenção de % permite comparação entre títulos com diferentes valores de face."
2	Responda perguntas implícitas	Antecipe de 1 a 3 perguntas que o aluno ainda não fez	Silêncio sobre cupons → "O cupom muda alguma vez? Não para taxa fixa. Sim para FRNs (redefine periodicamente)."
3	Intuição de convergência ao par	Explique que a convergência do preço para o valor de face no vencimento é mecânica	"O preço converge para o par porque o tempo encolhe + o VP dos FCs restantes converge para o principal. Não é impulsionado por taxas."
4	Cadeia causal primeiro	Lógica intuitiva antes da fórmula	Pular para a fórmula de precificação de títulos → "Novos títulos pagam 6%. Meu título paga 4%. O meu vale menos → preço cai até o rendimento igualar."
5	Contexto prático	Cada número ganha um significado real	"Duration 7,5" → "Aumento de 1% na taxa → queda de preço de ~7,5% (movimentos pequenos apenas; ajuste de convexidade para grandes)."
6	"Quão provável"	Informe frequências normais vs. raras	Omitir → "A curva de juros inverte raramente. Cada inversão precedeu uma recessão (~8 meses). Não perfeitamente preditiva."
7	Conceitos errôneos comuns	Sinalize de 1 a 2 erros específicos que iniciantes cometem	"Cupom mais alto = melhor título" → "Não. Títulos com desconto têm ganho de preço embutido no vencimento (acréscimo)."
8	Socrático em todo lugar	Toda seção de conceito incorpora pergunta Pense + resposta imediata	Aluno lê passivamente → forçado a parar, processar
9	Codificação dupla	Incorpore diagrama, gráfico ou hierarquia	Somente texto → fluxograma Mermaid da relação entre X e Y.
10	Feynman (Explicação)	No final, peça explicação simples e detecte lacunas	"Explique X" → "Explique X como se fosse para um colega que não conhece. Vou verificar se sua analogia está correta."
11	Dificuldade desejável	Varie o formato e a dificuldade entre módulos	MCQ apenas → misture MCQ, cloze, complete a frase, análise de caso.
12	Limite de orçamento	Mantenha módulo ≤3h, assunto ≤40h	Ignorar → rastreie o tempo gasto; se excessivo, restrinja o escopo.
13	Limite de tamanho do módulo	Mantenha lesson.md ≤12.000 caracteres	18.000 caracteres → divida em 2 módulos.
14	Progressão	Construa sobre pré-requisitos declarados	Pular para cálculo de convexidade sem duration → ensine duration primeiro.
15	Pular permitido	Com entrada esparsa, gere com padrões sensatos	"Não sei" → bloqueie → gere conteúdo de nível intermediário com revisão se necessário.
16	Distribuição de respostas	Chave de resposta MCQ distribuída uniformemente entre A-D	5x A consecutivos → alterne: B, D, A, C, A, B, D, C.

4. Ferramenta CLI (learn.sh)

# Escopo
learn.sh init <topico> [idioma] [nivel]

# Criar/gerenciar módulo
learn.sh create-module <topico> NN-nome
learn.sh list-modules <topico>
learn.sh remove-module <topico> NN-nome

# Validação
learn.sh validate-content <topico> [modulo]
learn.sh verify-all <topico>

# Quizzes cumulativos
learn.sh cumulative-quiz <topico> --from <primeiro-mod> --to <ultimo-mod>

# SRS (Repetição Espaçada)
learn.sh srs compile <topico>
learn.sh srs review <topico> [--due|--all]
learn.sh srs stats <topico>

# Utilitários
learn.sh status <topico>              # Progresso geral
learn.sh preview <topico> <modulo>    # Visualizar aula no terminal
learn.sh export <topico> --format pdf # (planejado)

Estrutura de Metadados da Aula

Cada lesson.md começa com:

---
module: NN-nome
learning_objectives:
  - CILO-1 descrição
  - CILO-2 descrição
prerequisites:
  - MM-nome
time_estimate: 2.5h
tags:
  - tag1
  - tag2
---

Formato de Quiz (quiz.yaml)

- question: "Texto da pergunta"
  options:
    A: Opção A
    B: Opção B
    C: Opção C
    D: Opção D
  answer: B            # Letra da resposta correta
  explanation: |
    Explicação detalhada de por que B está correto
    e por que as outras estão erradas.
  tags: [conceito-chave, aplicação]

Formato Cloze (cloze.yaml)

- text: "O _____ é a diferença entre a taxa de juros de mercado e a taxa de cupom."
  answer: prêmio do título
  hint: "Pense em spread vs. cupom"
  tags: [definição]

5. Sessão de Estudo Interativa

Quando o aluno executa learn.sh srs review <topico> ou estuda um módulo diretamente, a IA orquestra:

1. Ler: Apresentar aula com diagramas e blocos Prever/Cloze.
2. Explicar: "Explique [conceito] com suas palavras. Serei Feynman — tentarei encontrar falhas no seu raciocínio."
3. Praticar: MCQ com justificativa obrigatória. A IA explica distratores.
4. Julgar: "O autor diz X. Você concorda? Por quê? Que evidência contrária existe?"
5. Revisar: Cartões FSRS programados com base no desempenho anterior.

A IA adapta o tom, a profundidade e a velocidade com base nas respostas do aluno — se a explicação for fraca, mais sondagem socrática; se forte, avance mais rápido.

Exemplo de Sondagem Socrática em Linha

**Conceito**: Duration de Macaulay é o prazo médio ponderado dos fluxos de caixa.

**Pense**: Por que a duration é medida em anos, não em dólares?

**Resposta**: Porque é uma média ponderada por tempo (anos até o FC) ponderada pelo VP de cada FC. As unidades são anos × ($/$) = anos. É uma medida de tempo, não de valor monetário. Se você dissesse "a duration é 5", isso significa que o título se comporta como se todos os seus fluxos de caixa ocorressem em 5 anos, em média.

6. Como Começar

1. Clone este repositório.
2. Instale as dependências (consulte requirements.txt).
3. Execute learn.sh init "Aprendizado de Máquina" pt intermediário.
4. Siga o fluxo de criação de conteúdo para construir seu currículo.
5. Estude com learn.sh srs review "Aprendizado de Máquina".

Para obter ajuda: learn.sh help.

---

Construído com base nos princípios de Marva Collins, Richard Feynman e Robert Bjork.