anki/explain-it

O que explain-it faz?

Transforme o código que você investigou em um pequeno site HTML estático que um leitor inteligente sem contexto algum deste código possa acompanhar: uma página raiz que constrói o modelo mental, uma página por tópico e uma barra lateral conectando-os.

A meta: "linguagem simples que não seja simples demais nem difícil demais." Nunca fale de forma condescendente; nunca assuma conhecimento do repositório.

Fluxo de Trabalho

1. Investigue antes de explicar

Nunca explique código que você não leu. Para cada tópico, leia o código fonte de fato: as linhas alteradas, a função que as contém e pelo menos um ponto de chamada, para que você possa responder "quando este código é executado?" com uma história verdadeira. Se uma afirmação veio de outra pessoa (um comentário de revisão, uma issue), verifique-a no código primeiro e diga se não se confirma.

2. Planeje o site

• Uma página raiz (index.html): o guia introdutório. Ela constrói o modelo mental do sistema no leitor em ~2 minutos e linka para todas as páginas de tópico.
• Uma página por tópico (01-<slug>.html, 02-<slug>.html, …): cada página explica uma alteração, bug, decisão ou subsistema. 3–7 páginas é o ponto ideal; mescle tópicos em vez de exceder ~9.
• Uma barra lateral compartilhada em cada página listando todas as páginas em ordem de leitura, com a página atual destacada. As páginas são arquivos simples linkados com <a href> relativo — o site deve funcionar aberto diretamente do disco (file://), portanto sem roteadores, sem build, sem JS externo.

Pergunte ao usuário onde colocar a pasta apenas se nenhum local for óbvio; caso contrário, crie uma pasta com nome sensato ao lado do trabalho (ex.: docs/explainers/<topic>/) e informe onde a colocou.

3. Escreva cada página

Siga references/writing-guide.md para o método — leia-o antes de escrever sua primeira página. Os itens inegociáveis:

• Guia primeiro. A página raiz introduz cada conceito de domínio que as páginas de tópico precisam, cada um com uma metáfora concreta (ex.: "um release é uma fotocópia; um job em execução fixa uma fotocópia"). Introduza uma metáfora uma vez e depois reutilize-a exatamente igual em todos os lugares. Nunca empilhe duas metáforas para um conceito.
• Fundamente cada tópico na execução. Cada página de tópico abre com uma história "Quando este código é executado?": 2–4 passos de atores (Usuário faz X → Sistema executa função Y → o pequeno job interno). Nomes reais de funções em fonte de código, junto com — nunca em vez de — a história em linguagem simples.
• Mostre a alteração como diff. Código antigo vs novo em blocos de diff vermelho/verde com o caminho do arquivo no cabeçalho, aparado até o essencial, com 1–3 comentários inline apontando para o porquê — não narrando o quê.
• Quantifique o "porquê". "Lento" é proibido; "centenas de KB por requisição, ~99% do tempo para nada" é o padrão. O mesmo para risco: nomeie a entrada/estado concreto e o resultado errado.
• Separe bugs de decisões. Se algo é uma escolha defensável de produto, e não um defeito, apresente como uma decisão com a compensação, não como um erro.
• Termine a página raiz com um painel de status: uma tabela de status de cada item (feito / proposto / arquivado) com sua localização no código.

4. Construa o HTML

Copie references/site-template.html como ponto de partida para cada página — ele contém os tokens de design, a barra lateral e um exemplo funcional de cada componente (bloco de história, callout, bloco de diff, tabela de status, pills). Então:

• Mantenha cada página totalmente autocontida (todo CSS inline na página). A barra lateral é duplicada em cada página com o item atual marcado como class="on".
• Siga references/design-system.md para tokens e regras de componentes. Mantenha a paleta, o espaçamento e a escala tipográfica conforme fornecidos para que sites com várias páginas pareçam um único sistema. O template já inclui um alternador claro/escuro e uma barra lateral recolhível — mantenha ambos em cada página, não os remova.
• Sem dependências externas, exceto o link do Google Fonts já presente no template (a pilha de fontes cai graciosamente offline) e sem JS além do snippet de alternância de tema do template.

5. Verifique antes de entregar

Abra ou renderize a página raiz e pelo menos uma página de tópico (ou releia-as) e verifique: todo link da barra lateral resolve, todo identificador de código mencionado no texto existe no código com a grafia exata, todo diff compila conceitualmente contra o arquivo real, e os status do painel estão atualizados. Em seguida, informe ao usuário o caminho da pasta e abra a página raiz para ele se o ambiente permitir.

Armadilhas comuns

• Explicar de memória da conversa em vez do código — o explicador herda qualquer afirmação desatualizada. Releia a fonte.
• Deriva de metáfora: chamar de "fotocópia" em uma página e "cópia congelada" na seguinte. Um termo, em todos os lugares.
• Blocos de diff que colam 60 linhas na íntegra. Apare até o essencial; mantenha 2–4 linhas de contexto ao redor.
• Texto que narra o diff linha por linha. O diff mostra o quê; o texto só carrega por que é importante e quando é executado.
• Barra lateral que só existe na página inicial. Cada página carrega a barra lateral completa.
• Linguagem infantilizada ("o computador lembra das coisas em uma caixa especial"). O leitor é inteligente — ele só não conhece este código.