theshafinahmed/sproutly

O que sproutly faz?

Transforme material de estudo em UM curso HTML completo, autossuficiente e offline, no estilo Duolingo. Um motor pré-construído e testado cuida do aplicativo (abas, botão Voltar, progresso, modo exame, avaliação numérica, simuladores, mascote). Você escreve apenas o conteúdo, depois constrói e verifica com dois scripts. Nunca redigite o motor.

Esta é uma ferramenta de aprendizado, não um jogo: SEM corações, XP, sequências, chamas ou placares. Progresso = lições concluídas e respostas compreendidas.

Etapa 0: obter o motor (2 segundos)

SP="${SPROUTLY_HOME:-/tmp/sproutly}"
[ -f "$SP/scripts/build.js" ] || git clone --depth 1 https://github.com/theshafinahmed/sproutly "$SP"
ls "$SP/scripts"

Se esta skill estiver sendo lida de dentro do repositório sproutly, use essa pasta como SP. Se o clone for bloqueado (sem rede), peça ao usuário para anexar o repositório como um zip. Nunca reconstrua o motor manualmente.

Fluxo de trabalho

1. Ingerir. Leia cada arquivo por completo. Liste cada tópico, definição, fórmula, exemplo e exercício na ordem original. Anote slides com apenas imagem. Se o conteúdo principal for ilegível, diga isso e peça capturas de tela. Nunca invente o que um slide diz. (Se o usuário deu apenas um tópico, planeje o currículo, mostre-o e aguarde aprovação antes de escrever.)
2. Pergunte apenas se estiver bloqueado (arquivos ilegíveis, cursos não relacionados misturados, escopo pouco claro). Caso contrário, comece e declare as suposições em uma linha no final.
3. Planeje. De 6 a 10 unidades, 2 a 5 lições cada, fundamentos primeiro, mais o Chefe Final automático. Escreva uma lista de verificação de cobertura (cada tópico da fonte cai em uma lição), um plano de figuras e um plano de simulação por lição (ou "nenhum, porque...").
4. Escreva arquivos de conteúdo em ./content/ (um arquivo por unidade, para que as correções sejam pequenas e as unidades possam ser escritas em paralelo por subagentes se o usuário pediu rapidez). O arquivo 00-course.js contém apenas COURSE.title='...'; COURSE.slug='...';. Em seguida 01-unit.js, 02-unit.js... cada um chamando UNIT(...), e 99-end.js com CHEAT(...) e COVERAGE(...).
5. Construa: node "$SP/scripts/build.js" Nome-do-Curso.html content/
6. Verifique: node "$SP/scripts/verify.js" Nome-do-Curso.html --shots shots (adicione --allow heart para palavras de biologia). Ele verifica sintaxe, formato dos dados, perguntas independentes, avaliação numérica, cada simulação contra sua fórmula ref(), figuras, reproduz automaticamente cada lição, testa o botão Voltar, layout, persistência, funcionamento offline e cobertura. Corrija apenas o que imprime FAIL (edite o pequeno arquivo de unidade, reconstrua, execute novamente). Olhe para shots/*.png uma vez, corrija o que está claramente quebrado, pare.
7. Entregue com SendUserFile (display: 'attach', legenda de uma linha). Não publique como artefato a menos que solicitado.

Resposta final: 2 a 3 frases, tom de amigo espirituoso. Diga o que contém (unidades, lições, perguntas, figuras, simulações), que abre em qualquer navegador, funciona offline e o progresso é salvo naquele navegador e dispositivo. Mencione suposições e algo ilegível. Um empurrão honesto para usar diariamente. Não recapitule as etapas.

API de Conteúdo (todos os auxiliares já existem no motor)

UNIT('Nome da unidade', 'descrição de uma linha', [ L('u1l1','Título da lição',[ ...cartões ], ['fato chave 1','fato chave 2']) ]);
T(título, corpo, viz, {dica, humor, codigo})     // cartão de ensino. corpo = string ou array de frases curtas. viz = string svg. humor: happy|think
WORK(título, problema, [[o que fazemos, porquê],..]) // exemplo resolvido, um passo por toque
Q(q, certo, [errado1, errado2,..], porquê, {viz, codigo, armadilha})  // múltipla escolha. ESCREVA A RESPOSTA CERTA PRIMEIRO; o motor embaralha
TF(q, verdadeiro|falso, porquê, {viz, codigo, armadilha})
N(q, resposta, 'unidade', porquê, tol, {viz, codigo})  // número digitado. tol: omitir (1%) | {rel:0.02} | {abs:0.5} | {estrito:true, rel:1e-6}
M(q, [[esquerdo,direito],..], porquê)               // pares de correspondência, os valores direitos devem ser únicos
SIM('slider'|'toggle'|'stepper', título, texto, cfg)
RECAP(['marcadores simples'], [['nova palavra','significado simples']])   // último cartão de CADA lição
CHEAT({formulas:[..], tabelas:[{titulo,cabecalho,linhas}], glossario:[[termo,significado]], armadilhas:[..]})
COVERAGE([['tópico fonte','lessonId'],..])

Formatação de texto: **negrito**, `código`, V_{D} subscrito, x^{2} sobrescrito, \n quebra de linha. Tudo é escapado para HTML. T/Q/N aceitam codigo: (um bloco de código, ótimo para C ou qualquer curso de programação). Q(..., {armadilha:true}) também alimenta a lista de Armadilhas do Exame.

Simulações (sempre forneça tarefa e aviso; slider e toggle DEVEM fornecer ref):

SIM('slider','Ohm','texto',{
  entradas:[{id:'V',rotulo:'Tensão',min:1,max:24,passo:1,padrao:12,unidade:'V'}, ...],   // 1 a 3 sliders; também use como scrubber de linha do tempo
  modelo:function(v){ if(!v.R) return {saida:[],msg:'Circuito aberto: R deve ser maior que 0'};
     var I=v.V/v.R; return {saida:[{k:'I',rotulo:'Corrente',val:I,unidade:'A'}], fig:F.svg(...)} },
  ref:function(v){ return {I:v.V/v.R}; },   // RECOMPUTAÇÃO independente, verify.js compara com modelo()
  tarefa:'Dobre R.', aviso:'A corrente se reduz à metade.' });
SIM('toggle', ..., {entradas:[{id:'A',rotulo:'A está ligado',padrao:false}], modelo, ref, tarefa, aviso});
SIM('stepper', ..., {passos:[{legenda:'...', fig:F.svg(...)}], tarefa, aviso});

Unidades SI (A, V, Ω, W, F, H, Hz, s...) recebem prefixos automáticos (mA, kΩ). Proteja cada caso extremo (divisão por zero, raiz de negativo, log de 0) retornando msg, nunca NaN.

Figuras: F.svg(l,a,interno,rotulo), F.texto, F.linha, F.seta, F.circulo, F.ponto, F.caixa, F.eixos (retorna {svg,X,Y}), F.grafico(eixos,fn,xmin,xmax) (curvas vêm da fórmula real), F.mem (células de memória para C e arquitetura de computadores), F.centros, e circuitos: F.fio, F.res, F.fonte, F.terra. Precisa de mais formas? Adicione um arquivo a $SP/engine/js/figlib/ (é inlineado automaticamente) e mantenha os auxiliares genéricos.

Regras de conteúdo: ELI5 mas bem detalhado

Simples E completo. Nunca troque um pelo outro.

• Escreva para uma criança curiosa de 10 a 12 anos. Frases curtas (cerca de 15 palavras). Uma ideia por cartão. Palavra do dia a dia primeiro, termo técnico depois, e então use o termo consistentemente. Explique cada palavra técnica na primeira vez, bem ao lado dela. Nunca escreva "obviamente", "simplesmente", "trivialmente", "como sabemos".
• Ordem de ensino por conceito: por que existe (o problema), ideia central em uma linha, uma analogia do dia a dia, então o mecanismo ou fórmula precisa, depois um pequeno exemplo com números reais. Primeiros princípios, e sempre o porquê.
• Completo: cada slide, definição, fórmula, exemplo e exercício da fonte aparece em algum lugar. Não comprima várias ideias em um cartão. Lições têm de 6 a 14 cartões. Ideia difícil = mais cartões pequenos, não mais longos.
• Cartões de ensino: no máximo 4 frases curtas ou um bloco de fórmula, mais uma figura opcional. Faça uma pergunta após no máximo dois cartões de ensino.
• Cartões de fórmula: nomeie cada símbolo com sua unidade, diga em palavras simples o que acontece quando cada parte aumenta ou diminui, dê um pequeno exemplo resolvido.
• Toda lição termina com um RECAP (3 a 5 marcadores mais novas palavras) e tem chaves (1 a 4 fatos de uma linha; o botão Lembrar os mostra).
• Tom: melhor amigo espirituoso. Brincalhão, um pouco sarcástico, honesto, caloroso por baixo. Piadas leves, nunca às custas da clareza. Sem tom corporativo, sem "Ótima pergunta".
• O material enviado é a fonte da verdade, incluindo sua notação. Qualquer coisa que você adicionar é rotulada, ex.: "extra, não está nos seus slides".

Cada pergunta deve ser autossuficiente

Uma pergunta contém TUDO que é necessário: todos os valores com unidades, condições, significados dos símbolos e sua figura ({viz: ...}). Nunca escreva "o circuito acima", "o exemplo anterior", "como antes", "o mesmo valor", "o diagrama". Teste cada pergunta: "sozinha em uma tela em branco, um estudante que conhece o tópico poderia respondê-la?" (verify.js sinaliza essas frases.)

Números vêm do código

Defina constantes no topo do arquivo de unidade e derive texto, figuras e respostas delas (veja examples/test-fixture/course.js). Calcule cada resposta numérica com código, nunca manualmente. Respostas digitadas aceitam arredondamento correto, vírgula decimal, 7.3e-3, 22/3 e uma unidade final automaticamente; use tol apenas quando precisar de algo diferente e diga isso no texto da pergunta para perguntas de arredondamento exato.

Figuras: desenhe onde ensinam

• Assuntos pesados em figuras (EEE, física, química, biologia, geometria, arquitetura de computadores, lógica digital, estruturas de dados, algoritmos, redes, C e memória): uma figura em cerca de cada segundo cartão de ensino e em muitas perguntas.
• Assuntos médios: uma figura quando uma imagem vale mais que palavras (cerca de uma a cada 3 ou 4 cartões).
• Assuntos com poucas figuras (história, direito, literatura, idiomas): linhas do tempo ou fluxos de causa e efeito, um ou dois por lição, nenhum quando palavras são suficientes.
• Calcule posições a partir de variáveis de layout. Use o padrão de símbolos da fonte. Se não tiver certeza se uma figura está correta, simplifique-a e rotule-a como "simplificada". Uma figura correta e simples é melhor que uma figura bonita e errada.

Simulações: apenas onde há algo para sentir

Uma fórmula com variáveis, um processo com estágios, uma linha do tempo, uma forma de onda, uma máquina de estados. Busque pelo menos uma simulação na maioria das unidades de assuntos quantitativos ou de processo; nenhuma em história ou direito. Uma simulação sem uma verificação ref() bem-sucedida é corrigida ou removida.

Variedade de perguntas

Principalmente múltipla escolha (respostas erradas plausíveis, porquê de uma linha em palavras simples), N para cada cálculo, M de correspondência, TF para conceitos errados comuns e perguntas com armadilha:true para confusões sobre as quais o material alerta.

Aparência fixa

Tudo o que é visual (paleta, fonte arredondada, cores das unidades, Pip o mascote blob-broto, botões grandões, modo escuro, sem zoom, sem seleção de texto, abas inferiores) está integrado ao motor. Nunca mude Pip ou invente outro mascote. Não use nenhuma marca, personagem ou logotipo existente. Nomeie o curso de acordo com seu assunto.