Guia Editorial — regras operacionais do livro #

Versão operacional das orientações pedagógicas. A lei está na constituição; este guia é o que se consulta enquanto escreve.

1. O framework pedagógico em quatro linhas #

2. Esqueleto v5 de capítulo (obrigatório) #

O v5 é o v4 mais a seção histórica que o Princípio X tornou obrigatória. O v4, por sua vez, era o esqueleto v3 do livro de Engenharia de Harness mais as duas seções de interatividade. A ordem não é decorativa: ela é o Backward Design tornado sumário.

1. Objetivos de aprendizagem — 3–5, com verbo da tabela do §2.5, numerados **O1.**, **O2.**… Os identificadores são reais: cada exercício aponta para um deles, e o build falha se apontar para um que não existe.
2. O problema — por que este assunto existe. Comece pelo erro que alguém comete sem ele.
3. De onde isto veio — a história do método, em cinco elementos: o aperto (quem estava preso, em quê, quando) · o que se fazia antes · a virada (a ideia que destravou, sem notação) · a ideia reaproveitável (o padrão que serve fora deste método) · o nome. Fecha com a tabela de selos (✓ / ✓ᵐ / ⏳ / ❌ / 📖). Ver §2.4 e o Princípio X.
4. Fundamentos — a intuição, depois a matemática, depois o código. Nunca a fórmula sozinha.
5. Fundamentos científicos — 2–4 papers traduzidos para decisões ("o resultado X significa que, na prática, você deve Y"); ponteiro para bibliografia.md.
6. O estado da arte — o que é consenso hoje, o que está em disputa, e a cláusula de expiração do capítulo.
7. Mão na massa — a etapa correspondente do ml-zero, com o experimento que gera os números citados.
8. Pratique — os exercícios (mínimo 3). Ver §4.
9. Assista — os vídeos curados (mínimo 1) ou o laboratório. Ver §5 e §2.3.
10. Síntese + "o que levar" — leitura executiva e as ideias exportáveis para o trabalho do leitor.
11. Verificação — 2–3 perguntas abertas que testam exatamente os objetivos do item 1.

O item 3 admite duas posições, e só duas (ADR 0022, emenda 1.3.0 da constituição). A posição padrão é a acima: depois do problema e antes da intuição, porque antes do problema a história não tem a que se agarrar. A alternativa é ao fim do capítulo, quando é a prática que leva o leitor ao aperto: é o caso do II.2, em que o leitor vê duas rotas darem a mesma reta e um coeficiente mentir com R² de 0,982 antes de saber de onde veio o critério. O que não muda com a posição são os cinco elementos e a tabela de selos.

2.1 Cabeçalho obrigatório #

# 04 — Avaliação

> **Estado da arte capturado em 2026-08** · última revisão 2026-08-01 · [histórico](HISTORICO.md)

O selo diz ao leitor se a seção "estado da arte" está fresca — o que a data de um evento citado no corpo não faz.

2.2 Níveis de maturidade #

Todo capítulo declara seu nível no cabeçalho, logo abaixo da data. O leitor sempre sabe o que está lendo.

Por que existe. O livro serve a disciplinas em andamento: um capítulo que existe de forma honesta vale mais ao estudante do que um capítulo ausente. Mas cobertura sem rigor é o que este projeto recusa — então o nível é declarado, nunca silencioso. Baixar o rigor sem avisar seria fraude; declarar cria a dívida visível que o roadmap cobra.

Como promover. esqueleto → essencial é um ciclo de escrita; essencial → completo é um ciclo de aprofundamento (experimento próprio, fontes ✓, cláusula de expiração, revisão developmental). Cada promoção é uma spec.

2.3 Laboratórios interativos #

A terceira superfície do livro, ao lado de exercício e vídeo:

Um laboratório roda inteiro no navegador. Não há gabarito a esconder — o gabarito é o comportamento do próprio objeto. Isso o torna a superfície mais robusta do livro: funciona mesmo com o backend fora do ar.

O laboratório vem antes da explicação — e há uma fronteira que esta regra não declarava. Praticar antes de ser ensinado rende em conceito e transferência (g = 0,36) e não rende em procedimento (g = −0,03) — Sinha & Kapur, 2021, 53 estudos. Num ato de procedimento, o exemplo trabalhado vem primeiro, e o leitor produz depois.

E a prática tem de ser assistida: descoberta sem apoio rende d = −0,38, e com feedback, exemplo e andaime rende +0,30 (Alfieri et al., 2011). A diferença é de sinal, não de grau.

A evidência inteira, com o selo de proveniência de cada achado, a fronteira onde ele deixa de valer e a fila de verificação, está em BASE-EDUCACIONAL.md. Os dois números acima ainda estão em ⏳, e o documento diz o que isso permite e o que não permite.

A condição que quase ninguém cumpre: a explicação que vem depois tem de construir sobre o que o leitor tentou (g = 0,56, contra 0,20 quando ignora). Laboratório seguido de texto genérico é a versão que produz os efeitos pequenos. Ver ADR 0022.

Regras de autoria:

• O bloco declara o que manipular ali ensina e, sobretudo, o que o leitor deve descobrir sozinho. Um laboratório que explica antes de deixar brincar desperdiça o próprio mecanismo.
• Ponha o laboratório antes da explicação, não depois. A descoberta vem primeiro; o texto confirma e nomeia.
• Prefira laboratórios em que o fracasso ensine. O melhor exemplo do livro é o XOR no capítulo III.1: o leitor trava em 3 de 4 e descobre a impossibilidade com as próprias mãos — o que nenhuma frase entrega.
• Quando não houver vídeo verificável para um tema, o laboratório cumpre a cota de mídia. Inventar uma referência para preencher cota é violação do Princípio I.

Sintaxe em BANCO-DE-EXERCICIOS.md; os widgets vivem em publicar/tema/laboratorios.js.

2.4 "De onde isto veio" — como se escreve #

Materializa o Princípio X. Portão do nível essencial, para todo capítulo de método.

Os cinco elementos, nesta ordem. O aperto (quem, em quê, quando — gente e data, não "os pesquisadores") · o que se fazia antes (contra o quê o método compete) · a virada (a ideia que destravou, em linguagem natural, sem notação) · a ideia reaproveitável · o nome, se tiver origem.

O quarto elemento é a razão de a seção existir. Todo artifício técnico declara a ideia reaproveitável que há por trás dele: artifício sem ideia é truque, e truque não se transfere. Se você não consegue escrever esse parágrafo, ou ainda não entendeu o método, ou ele não merece capítulo.

A tabela de selos fecha a seção. Uma linha por afirmação histórica:

Conferir um DOI dá ✓ᵐ, nunca ✓. Diferente da legenda de bibliografia.md, que responde a outra pergunta ("esta referência pode sustentar uma afirmação?"): lá um ✓ conferido só por identificador equivale a ✓ᵐ aqui.

❌ é permitido e às vezes é o melhor que há. Exemplo real, no capítulo III.1: a atribuição do backpropagation a "um italiano em 1979" não foi confirmada — o capítulo diz que procurou e não achou, e lista o que existe (Linnainmaa 1970, Werbos 1974, Fukushima 1979/80). Lacuna admitida em voz alta vale mais que suposição com cara de fato.

Três proibições. Gênio solitário (história ruim e geralmente falsa: métodos nascem de instituições, encomendas, prazos e restrições materiais — e é isso que ensina) · curiosidade decorativa (se o parágrafo sai sem o leitor perder compreensão ou julgamento, é enfeite) · misturar registro ("a literatura atribui a X" ≠ "X publicou em 19NN", e as duas não podem parecer iguais no texto).

Pesquise de uma vez, não capítulo a capítulo. A pesquisa histórica vai numa sessão própria, com nota em estudos/ e fila de verificação ao final, ordenada por dúvida fechada por unidade de esforço. As histórias se conectam, e quem descobre a conexão depois já publicou os dois lados sem ela.

Duas armadilhas. Resumo de busca não é fonte — nem para confirmar nem para desmentir; um resumo pode abreviar o original a ponto de um fato correto parecer errado, e corrigir a partir dele introduz o erro que você achava estar consertando. Ler a fonte também serve para achar o que você não sabia que estava lá — as melhores histórias estão no parágrafo que ninguém resumiu.

O teste: o leitor termina a seção querendo continuar. Um livro técnico compete com a tentação de pular para a fórmula; a história é o que dá ao leitor um motivo para não pular.

2.5 Verbos de objetivo — a tabela de Bloom #

O esqueleto pede "verbos de Bloom" desde o começo, e a tabela nunca existiu no repositório. Quem escrevia um capítulo lembrava de cabeça — e o resultado é o que a auditoria de 2026-08-12 mediu: dos 15 objetivos declarados no nível Criar, um único tinha exercício que pede produção. O verbo prometia projetar e o exercício cobrava múltipla escolha.

A tabela é a revisão de Anderson & Krathwohl (2001), não a pirâmide de 1956. A diferença importa: a revisão troca substantivos por verbos e acrescenta uma segunda dimensão — o tipo de conhecimento.

Os quatro tipos de conhecimento #

A segunda dimensão é a que a pirâmide esconde. Dá para "aplicar" a vida inteira sem nunca tocar o metacognitivo — que é justamente saber quando o método não serve, e é o que este livro mais quer ensinar.

Três regras de escrita, e a mais importante é a terceira #

1. Um verbo por objetivo. "Calcular e interpretar" são dois processos; um deles sempre fica sem exercício. Dos 114 objetivos do livro, 22 empacotavam dois — e em todos, só metade era cobrada.
2. Nunca "entender", "conhecer", "saber", "dominar". Não se verificam, e o build falha se encontrá-los abrindo um objetivo.
3. O exercício define o verbo, não o contrário. Escreva primeiro a evidência que você aceitaria; o verbo é o nome do que ela cobra. Se você declarou "projetar" e a evidência é uma múltipla escolha, o objetivo não era projetar — era reconhecer. Rebaixar o verbo é honesto; inflar o verbo é promessa que o leitor descobre sozinho, tarde.

Cuidado com "reconhecer" e "identificar". Em Anderson & Krathwohl são subprocessos de Lembrar. No livro foram usados com sentido de julgamento — e a mesma palavra gerou um exercício de nível 1 e outro de nível 5, quatro degraus de distância. Se o que você quer é julgamento, escreva avaliar ou decidir.

3. Regras de escrita permanentes #

• Evidência por experimento: toda afirmação empírica cita o script que a produziu (ml-zero/etapa-04/experimento.py), com dataset, seed e versão da biblioteca. Sem isso, é intuição — e se escreve como intuição.
• Nenhum número sem procedência. Nem "cerca de 90%", nem "costuma dobrar". Ou mede, ou cita, ou não afirma.
• Intuição → matemática → código, nessa ordem. Uma fórmula que aparece antes da intuição é carga cognitiva pura.
• Uma ideia nova por seção. Se a seção precisa de duas, são duas seções.
• Termos técnicos consagrados sem tradução forçada (overfitting, embedding, batch, drift); traduzidos quando a prática já traduziu (viés, variância, acurácia).
• Tabelas para fatos enumeráveis; explicação vive na prosa, não nas células.
• Cada componente descrito deve, quando possível, declarar sua cláusula de expiração.

4. Como se escreve um exercício #

A sintaxe completa está em BANCO-DE-EXERCICIOS.md. As regras editoriais:

• Todo exercício rastreia até um objetivo ("objetivo":"O2"). Sem isso, o build falha.
• O feedback (> **porque:**) é obrigatório e explica o conceito — não apenas nomeia a resposta certa. Escreva-o pensando em quem errou, não em quem acertou.
• > **volte para:** aponta a âncora da seção que resolve a dúvida. É o gesto mais útil do livro.
• Errar é parte do ciclo: o gabarito só é revelado na segunda tentativa. Escreva o enunciado sabendo que o leitor vai tentar de novo.
• Distratores plausíveis. Uma alternativa errada que ninguém marcaria não ensina nada. As melhores são as que capturam um mal-entendido real e comum.
• Ordem de dificuldade dentro do capítulo: reconhecimento → aplicação → julgamento.
• Exercício de código é sempre completion problem (Sweller): complete a lacuna, não escreva do zero. Criar do zero é trabalho da etapa do ml-zero.

5. Como se escolhe um vídeo #

• Um vídeo entra por aquilo que o texto não faz bem. Geometria animada, som, ritmo de derivação no quadro. Se o vídeo só repete o capítulo, ele não entra.
• Declare autor, duração e o que ele resolve. O campo de justificativa é obrigatório.
• Prefira material estável e gratuito. Vídeo atrás de paywall não entra (Princípio VI).
• Reconfira os links na janela de revisão. Vídeo morto é dívida do livro vivo, não do leitor.
• A carga do player só é pedida ao servidor de origem depois do clique do leitor — privacidade por padrão.

6. Datação, histórico e expiração #

1. Todo capítulo declara a data de captura no cabeçalho.
2. Distinguem-se três datas: do evento (imutável), da captura (quando fotografamos) e do experimento (quando o número foi medido, com a versão da biblioteca).
3. Toda edição atualiza HISTORICO.md: changelog, snapshot por capítulo e o registro de expiração (🔵 aberta / 🟡 em curso / 🟢 confirmada / 🔴 refutada), com a versão do modelo de IA usada.

Regra de escrita associada: quando uma afirmação for sensível ao tempo ("hoje", "ainda não", "o consenso de 2026"), ela está implicitamente sob a data de captura do cabeçalho. Evite absolutos atemporais ("nunca", "sempre") a menos que sejam do tipo que não expira.

7. Revisão em duas camadas #

Antes do copyedit de superfície, um passo de revisão developmental: re-ver estrutura e sentido. O argumento fecha? A ordem serve ao leitor? Há redundância ou lacuna? Os exercícios testam mesmo os objetivos declarados, ou testam o que foi fácil de perguntar?

"Escrever é reescrever." Nenhum trecho novo é publicado sem esse passo — é portão de qualidade da constituição (Princípio IX), não sugestão.

8. Siglas e glossário (política) #

• Toda sigla é apresentada por extenso na 1ª ocorrência de um capítulo ("Support Vector Machine (SVM)") e dali em diante o texto pode usar só a sigla.
• O motor reforça isso: envolve automaticamente cada sigla conhecida em <abbr>, de modo que passar o mouse revela o significado em qualquer ocorrência, sem poluir o texto-fonte. O mapa vive em publicar/siglas.mjs e é espelhado em glossario.md; a asserção H de publicar/jornada.mjs abre a página e cobra que nenhuma sigla conhecida chegue nua ao leitor.
• Ao introduzir uma sigla nova, adicione-a nos dois lugares e confira a expansão na fonte (Princípio I).

9. Fluxo repetível para um contribuidor #

1. Abrir o tema — pesquisa dupla (científica + indústria), verificada por busca cruzada; registrar lacunas.
2. Definir os objetivos primeiro (Backward Design) e, logo em seguida, os exercícios — antes de escrever o corpo. Se você não consegue escrever o exercício, o objetivo está vago.
3. Reunir a evidência — rodar o experimento no ml-zero; anotar seed, versões e números.
4. Escrever — no esqueleto v5, um tipo de texto por seção (Diátaxis).
5. Revisar (developmental) — §7.
6. Verificar fontes — nenhuma URL/DOI inventado; não-confirmado marcado ⏳; sincronizar bibliografia.md.
7. Gate de build — npm run build (em publicar/) verde: link-check e gate de exercícios.
8. Datar — selo no capítulo, entrada no HISTORICO.md com a versão do modelo de IA, entrada no CHANGELOG.md.

10. Cadência do livro vivo #

• Janela trimestral: reconferir vídeos, reexecutar os experimentos com as versões correntes das bibliotecas, atualizar o placar de expiração e as datas de revisão.
• Gatilho extraordinário: qualquer evento que invalide uma "Leitura executiva" (um resultado replicado que derruba uma recomendação, uma biblioteca central descontinuada, um dataset retirado) dispara revisão pontual do capítulo afetado, sem esperar a janela.
• Gatilho por telemetria: exercício com taxa de acerto muito baixa e volume relevante é sinal de que o texto está mal escrito, não de que o leitor é fraco. Ele entra na fila de revisão.