Walid-Ahmed/flashcard-deck

Baralho de flashcards

Transforme um assunto em um baralho de cartões pergunta-e-resposta que ensinam o conceito geral primeiro, imprimem de forma limpa e podem se tornar vídeos no YouTube. Os cartões são escritos em um único arquivo Python (deck.py) com pequenos auxiliares, e scripts agrupados renderizam tudo a partir dele, de modo que uma correção em um cartão é uma edição e uma reconstrução.

O trabalho ocorre em quatro etapas. Pergunte antes de cada etapa que custa tempo do usuário ou publique algo, porque um baralho só é útil se cobre o que eles precisam, e os vídeos levam minutos para serem codificados.

1. Entrevista: pergunte o que construir.
2. Plano: proponha tópicos e perguntas dos cartões; obtenha um sim.
3. Cartões: escreva deck.py, renderize, veja cada cartão, corrija o que não se encaixa.
4. Extras (apenas se desejado): vídeos, miniaturas, publicação.

1. Entrevista

Comece perguntando, não construindo. Use a ferramenta AskUserQuestion para que o usuário possa clicar nas respostas. Faça todas as perguntas em uma única chamada (ela aceita até 4 perguntas) e pule qualquer pergunta que a mensagem do usuário ou o projeto aberto já responda. Ofereça uma opção recomendada primeiro, marcada como "(Recomendado)".

Pergunte sobre o seguinte. A ferramenta aceita até 4 perguntas; portanto, quando a fonte for o material do usuário e uma quinta pergunta for necessária, faça a última em uma segunda chamada.

• Fonte: o que os cartões cobrem. Opções como: material que o usuário já possui (arquivos ou uma pasta: PDFs, slides, anotações em Word ou Markdown, um curso, um repositório ou flashcards existentes), este repositório, um assunto do seu próprio conhecimento ou anotações que o usuário colará. Se a solicitação já nomear a fonte, pule esta.
• Quão fielmente seguir (apenas quando a fonte é o material do usuário): apenas o que o material diz (Recomendado), o material mais conceitos básicos ausentes marcados como adicionados, ou o material como ponto de partida.
• Público e profundidade: iniciante (uma ideia por cartão, palavras simples), intermediário (conceitos mais um pequeno exemplo de código) ou avançado (trade-offs, casos extremos).
• Número máximo de cartões: até 10 (um conjunto rápido), até 20 (Recomendado), até 40 (um curso completo) ou sem limite (quantos o material precisar). O usuário pode digitar qualquer outro número. Registre como deck(..., max_cards=N): a construção para se o baralho ultrapassar esse valor, de modo que dividir cartões depois não possa quebrar silenciosamente o limite. Mais cartões significam mais tópicos, não cartões mais longos.
• Saídas: apenas imagens e PDFs dos cartões (Recomendado), mais vídeos, mais vídeos e miniaturas. Os vídeos vêm depois que os cartões são aprovados, de qualquer forma.

Em seguida, se ainda não souber, pergunte em texto simples (sem necessidade de ferramenta): o título do baralho mostrado em cada cartão (como "FastAPI" ou "Kubernetes"), onde salvar a saída (sugira uma pasta flashcards/ no projeto atual, ou uma nova pasta) e se exemplos de código podem nomear o projeto fonte ou devem permanecer genéricos. Para material do próprio usuário, pergunte também se cada cartão deve mostrar de onde veio (como "Cap. 3, p. 42").

2. Plano

Leia a fonte primeiro. Se for material que o usuário já possui, leia references/existing-material.md agora: ele cobre a leitura de PDFs, slides, arquivos Word, pastas e flashcards existentes, mapeando todo o material para que nada seja silenciosamente deixado de lado, permanecendo fiel a ele e apontando cada cartão de volta para sua página. Para um assunto do seu próprio conhecimento, decida o que um aluno no nível escolhido precisa. Em seguida, proponha o baralho como uma lista curta: tópicos na ordem de aprendizado e, abaixo de cada um, uma linha por cartão com sua pergunta. Agrupe por conceito (fundamentos de HTTP, validação, autenticação), não por arquivo. Mire em 3 a 9 cartões por tópico. Um baralho pequeno (abaixo de cerca de 12 cartões) funciona como 2 ou 3 tópicos de 2 a 4 cartões.

Mantenha o plano dentro do número máximo de cartões e deixe espaço para uma ou duas divisões. Se o material precisar de mais cartões do que o máximo permite, cubra primeiro as ideias centrais, depois liste os tópicos ou seções deixados de fora e ofereça aumentar o limite.

Mostre o plano e peça um sim, alterações ou cortes antes de escrever os cartões. Escrever 40 cartões sobre os tópicos errados desperdiça mais tempo, então essa verificação vale uma ida e volta.

3. Cartões

Escreva deck.py, primeiro tópico primeiro

Copie references/deck_template.py para o local onde a saída será gerada. Escreva os cartões do primeiro tópico, renderize apenas esse tópico (--topic 1), mostre dois ou três deles ao usuário e pergunte se o estilo e a profundidade estão corretos. Depois escreva o restante. Descobrir no cartão 3 que o usuário queria cartões mais curtos é barato; descobrir no cartão 40, não. Leia references/components.md antes de escrever o primeiro cartão: ele mostra cada bloco de construção (frase principal, caixas, etapas, tabelas, exemplos de código, notas, diagramas) com o HTML a ser usado.

Como escrever um bom cartão e por quê:

• Conceito primeiro. A pergunta e a frase de abertura (o lead) enunciam a ideia geral em palavras que se aplicam em qualquer lugar. O código específico do projeto vai em uma caixa example(...) legendada "Exemplo: ...", para que o leitor aprenda a regra e depois veja um caso. Quando o exemplo do projeto diferir da prática comum, diga isso no comentário do exemplo.
• Uma ideia por cartão. Uma pergunta que une duas ideias separadas ("O que é X e como implantá-lo?") deseja dois cartões. Um contraste ("Como X é diferente de Y?") ou um par que só faz sentido junto é uma ideia.
• Lead, depois estrutura, depois exemplo. Uma resposta de uma ou duas frases, depois duas ou três caixas, etapas ou uma pequena tabela que a detalham, depois uma nota opcional e um exemplo de código. O leitor deve obter a resposta apenas pelo lead.
• O rodapé é a linha para lembrar, com menos de 15 palavras. A tag é uma ou duas palavras nomeando a ideia.
• Redação simples e exata. Frases curtas. Nomeie códigos de status reais, nomes de funções e comandos; não insinue.
• Diagramas apenas onde acrescentam algo: um fluxo, uma decisão com caminhos de falha ou as partes de uma URL ou mensagem. Não em cartões cuja tabela já mostra a estrutura.
• Referências cruzadas dizem onde olhar: "O Cartão 4 em Estrutura do app mostra o lado do servidor."

Renderize e verifique

python3 <skill-dir>/scripts/build_deck.py deck.py --out OUT_DIR             # todos os cartões, PDFs, README
python3 <skill-dir>/scripts/build_deck.py deck.py --out OUT_DIR --topic 1   # um tópico, verificação rápida

<skill-dir> é a pasta onde este SKILL.md está. Use python3, ou python onde isso for Python 3. O script precisa de Python com playwright e Pillow (pip install playwright pillow), além do Google Chrome ou playwright install chromium. Ele renderiza cada cartão como PNG A4 paisagem de 2400 x 1698 px, verifica se o conteúdo de cada cartão cabe (altura e largura) e para de nomear qualquer cartão que não caiba. Em seguida, escreve um PDF por tópico, print/all-cards.pdf e README.md.

• Conteúdo repetido: a verificação de ajuste mede o tamanho, não o sentido. Procure por uma caixa que repete uma etapa ou o lead, e corte-a.
• Acima do máximo: a construção para se o baralho tiver mais cartões que max_cards. Mescle ou descarte os cartões menos importantes, ou peça ao usuário para aumentar o limite. Não aumente por conta própria.
• Um cartão não cabe: encurte o texto, remova uma caixa ou divida-o em dois cartões (como "9a" e "9b", ou duas perguntas). Nunca reduza a fonte para forçar a entrada; os cartões devem permanecer legíveis quando impressos.
• Olhe para cada cartão após a renderização, abrindo os PNGs. A verificação de ajuste detecta estouro, mas não um cartão confuso, um diagrama que engana ou um erro de digitação. Corrija e re-renderize; --topic N re-renderiza um tópico rapidamente.
• Espaço sobrando é normal. A construção relata espaço sobrando em px CSS no cartão de 1200 x 849 (o PNG é o dobro). Um cartão simples frequentemente deixa 150 a 350 px vazios, e isso é bom para leitura e impressão. Não preencha um cartão para ocupar espaço. Se um cartão deixar mais de cerca de 400 px e parecer ralo, pode merecer um diagrama ou um exemplo, ou pode ser mesclado a um cartão vizinho.

4. Extras: vídeos, miniaturas, publicação

Apenas quando o usuário os desejar e depois que aprovar os cartões. Pergunte qual estilo de vídeo e diga aproximadamente quanto tempo a codificação leva (cerca de 15 segundos de codificação por cartão em um laptop).

python3 <skill-dir>/scripts/build_videos.py deck.py --cards OUT_DIR --out VIDEO_DIR [--mode both|questions|cards]
python3 <skill-dir>/scripts/build_thumbnails.py deck.py --cards OUT_DIR --out VIDEO_DIR/thumbnails [--mode both|questions|cards]

• --mode both (padrão): cada pergunta com a resposta oculta e uma barra de tempo (6 s), depois o cartão completo (12 s).
• --mode questions: um quiz, cada pergunta por 10 s, sem respostas.
• --mode cards: uma revisão, cada cartão completo por 15 s.
• Cada modo gera um vídeo por tópico e um com todos os cartões, nomeados com o modo (-questions, -cards) para que estilos nunca se sobrescrevam. Passe o mesmo --mode para build_thumbnails.py para que seus nomes coincidam.
• Cada vídeo tem telas de introdução e título do tópico, e uma descrição .txt cujos capítulos o YouTube transforma em seções clicáveis. Os capítulos têm pelo menos 10 segundos, o que o YouTube exige.
• Os vídeos precisam de ffmpeg. Mantenha VIDEO_DIR fora de qualquer repositório git, pois os vídeos são grandes.
• As miniaturas são JPEGs 1280 x 720 nomeados para corresponder a cada vídeo. topic(..., hook="A · B · C") define a pequena linha abaixo do título de cada tópico.
• Após a construção, ofereça títulos e descrições prontos para o YouTube: um título com menos de 70 caracteres com o assunto e o hook, uma descrição com a linha de abertura, um marcador por tópico, quaisquer links e os capítulos do .txt.

Pergunte antes de enviar, publicar ou carregar qualquer coisa; essas ações alcançam outras pessoas. Se os exemplos de código do baralho vierem do curso ou repositório de outra pessoa, mencione isso antes de torná-lo público e ofereça uma linha de crédito (deck(..., credit="...") coloca uma no README).

Alterando um baralho depois

Edite deck.py e execute build_deck.py novamente; ele reconstrói cada cartão, os PDFs e o README, e remove imagens de cartões excluídos. Reconstrua vídeos apenas se o usuário quiser que sejam atualizados, e --descriptions-only reescreve apenas as descrições dos vídeos.

Arquivos nesta skill

• scripts/build_deck.py: cartões, verificação de ajuste, PDFs, README.
• scripts/build_videos.py, scripts/build_thumbnails.py: os extras.
• scripts/flashcards/: auxiliares que deck.py importa (__init__.py), o renderizador (engine.py) e a folha de estilo dos cartões (card.css: amigável para impressão, branco com contornos coloridos, A4 paisagem fixo).
• references/components.md: cada bloco de construção do cartão com um exemplo. Leia antes de escrever cartões.
• references/deck_template.py: um pequeno baralho funcional para copiar.
• references/existing-material.md: construir um baralho a partir das próprias anotações, PDFs, slides, repositório ou flashcards do usuário. Leia quando essa for a fonte.