moyhig-ecs/coread-explainer

coread-explainer — Explicador Auditado de Co-leitura

Esta skill tem duas camadas. Como desenhar usa o kit anatomy (câmera isométrica, sombreamento em quatro etapas, moldura com cartão, componentes). O conteúdo desta skill é a disciplina e a mecânica sobre ele: ler apenas dados congelados, recontar números, exibir limitações em tela cheia, manter um livro-razão do que pode / não pode ser dito, e transformar perguntas levantadas pela figura em cartões de verificação com respostas. A figuração é uma superfície para "alinhar o entendimento humano com a leitura da IA", não uma decoração. Portanto, se a origem de um único número não puder ser rastreada, a credibilidade de toda a figura cai.

O primeiro modelo são as entradas de figuração em várias versões (v1 a v5). As entradas modelo podem ser obtidas pelo DOI da galeria (10.5281/zenodo.23992312 · DOI conceitual de todas as versões). Em caso de dúvida, leia seus NOTES, CLAIMS e README.

0. Decisões a serem tomadas antes de começar (escrever no BRIEF)

Solicitações de figuração sempre são convertidas em um BRIEF (pedido de compra) antes de serem criadas. Sem um BRIEF, o criador lê fora do material, coloca números manualmente e define seus próprios critérios de avaliação. O que escrever no BRIEF:

1. A solicitação literal (as palavras da pessoa que solicitou, exatamente como ditas · data).
2. O leitor e a avaliação final (padrão são três. Substitua se houver outro leitor):
   • E1 editor: A figura e o texto são fiéis ao artigo (ou relatório), não afirmam o que o artigo não afirma. Qualidade para ser publicado como figura ou apêndice do artigo.
   • E2 autor do vídeo: Apenas com a captura de tela 1920 × 1080 e o roteiro, é possível criar uma cena de 1 a 2 minutos. O núcleo é visível nos primeiros 10 segundos.
   • E4 "Esta leitura veio deste instrumento": O controle positivo, a elegibilidade, e o fato de que a leitura muda ao trocar faixas ou condições são visíveis na captura como uma cadeia de evidências.
   • Se o leitor for substituído, escreva também o teste de aceitação medido por esse leitor (ex.: para alunos em sala de aula, três perguntas a serem respondidas após ver a figura, e o critério de resposta correta). Apenas manter os nomes E1 / E2 / E4 não é suficiente para avaliar uma figuração voltada para alunos.
3. Lista de materiais (caminho absoluto · ler apenas estes) e o que não ler (pastas de outros criadores, julgamentos, memória).
4. Valores para verificação (alguns valores que a camada de execução leu dos dados). Se não conferirem, escreva que os dados estão corretos.
5. Local de armazenamento (entry_<cartão>_vN/ · não sobrescrever a pasta da versão anterior) e rascunho (subdiretório separado para cada criador).
6. Prazo de entrega (minutos) e o que retornar (≤ 10 linhas: arquivos, número de estados, capturas, resultados da verificação, o ponto de menor confiança).

→ O modelo está em references/brief-template.md.

1. Contrato de dados (data contract)

• Ler apenas as saídas congeladas do cartão (JSON, npz, figuras png). Cartão = PREREG (pergunta, universo, controles, critérios, o que não afirmar) + script + saída (proveniência = commit, dirty, md5). Não colocar números de fora do cartão na figura.
• Não importar nem executar o script do experimento (scripts de sumarização sem proteção main podem, ao serem importados, reescrever resultados congelados). Apenas ler os arquivos de dados.
• Os números são produzidos pelo script a partir dos dados. Não copiá-los manualmente para HTML ou roteiro. Os números produzidos são recontados por dois ou mais caminhos independentes (ex.: assert em Python do pack, JS da página, lado do kernel, check_claims.py com âncoras = arquivo, chave e valor esperado). Se discrepantes dos valores de verificação, considere os dados como corretos e informe o solicitante.
• Cercas para valores truncados: O rank truncado superiormente (ex.: abaixo do 1000º lugar = 1001) é desenhado com névoa, cor uniforme, e não é descrito ou dito como "afundou" ou "foi suprimido". Alinhar a ordem do truncamento (truncar antes da mediana ou mediana antes de truncar) com a descrição e implementação do cartão. Se houver discrepância na mediana com número par de elementos, divulgar.
• Valores de faixas ou condições não elegíveis são mostrados apenas como um dos lados da comparação, com um cartão dizendo "não passou pela auditoria". Não desenhar nulos como "ausente".
• Linhas provenientes da mesma semente e da mesma família de prompts não são contadas independentemente (especificar a contagem, como "são 3 cenas diferentes").
• A leitura (L3) do RESULT não são dados. Antes de copiar uma frase do RESULT para a figura, verificar se a frase se sustenta com os números dos dados. Já houve caso de confundir uma afirmação sobre proporções com uma sobre quantidades ("a maioria dos top são prenúncios e ecos" = correto em proporção por posição, mas em quantidade a posição basal ocupou 80%). Se não se sustentar, não copiar para a figura, colocar no livro-razão como "não pode ser dito", e solicitar correção ao lado do RESULT.
• Arquivos que estão crescendo são passados como cópia congelada (log, registro diário): escrever o intervalo de linhas e md5 no BRIEF; o criador lê apenas esse intervalo. Evitar que registros adicionados posteriormente (ex.: respostas de avaliação) se misturem ao material.

→ Detalhes e armadilhas em references/data-contract.md.

2. O que construir (uma pasta de entrada)

entry_<cartão>_vN/
  build.mjs            Monta o ESM / CSS da página e do widget a partir do kit (não editar HTML manualmente)
  pack_*.py            Dados → pacote da figura (primeiro caminho de recontagem com assert)
  data.mjs / live.js   Máquina de estados da página, renderização (segundo caminho de recontagem)
  i18n.js              Textos em ja / en
  *_widget.py/.js/.css anywidget (traits: state, row, t, layer, band, lang, theme, etc.)
  demo_marimo.py  demo_jupyter.ipynb
  check_claims.py  make_check.py  run_*.sh   Verificações (§5)
  captures/            Capturas de tela (§6)
  CLAIMS.md  NOTES.md  README.md  SCRIPT_yukkuri.md
  (Camadas internas em arquivos separados: *_layer.js / *.css / README_internal.md — §8)

• Capítulos e estados: Criar uma figura que percorre os estados (0, 1, 2 …) e agrupá-los em capítulos (ex.: cena → auditoria → cena principal → uma rodada de co-leitura → livro-razão). Acima da sequência de números de estado, colocar botões de capítulo (ao clicar, vai para o primeiro estado do capítulo). Posicionar os botões de capítulo e estado acima dos títulos (no topo da página) (.sh-nav · fixo no topo da tela em páginas): se colocados abaixo, os botões se movem verticalmente conforme o tamanho do título de cada estado, fazendo com que se percam após o clique (solicitante 10/28 noite: "Ao clicar no botão, perco-o de vista devido às diferentes alturas da página; coloque no topo, sem movimento vertical" · antes da correção, a posição variava mais de 900 px entre estados). Incluir na verificação "o topo da faixa de botões é o mesmo em todos os estados". Se renumerar os estados, gerar uma lista de títulos (número do estado → título) e verificar manualmente (já ocorreu duplo deslocamento no script de renumeração).
• Widget não deve ser encapsulado em iframe. As operações na figura devem chegar ao Python, e o Python deve poder escrever o estado (bidirecional). Funcionar tanto em marimo quanto em JupyterLab.
• A página terá 4 variantes (escuro / claro × ja / en) geradas a partir do build.

→ O modelo de implementação está em references/implementation.md (esqueleto baseado nas entradas modelo). O modelo mínimo está em assets/ (esqueleto que passa por build, verificações e capturas com dados sintéticos: config.json é o único local para números de estado, capítulo e moldura / run_checks.sh / list_headings.py / _smoke/ com evidências de funcionamento). Novas figurações começam copiando daqui.

3. Disciplina de linguagem (livro-razão: pode dizer / leitura / não pode dizer)

O livro-razão é o último capítulo da figura. Cada linha tem origem (arquivo e chave):

• Pode dizer (L1): Cópia do valor dos dados, julgamento congelado.
• Leitura (L3): Especificar de quem é a leitura (camada de execução / criador), rotular como "aceitação é humana", e marcar frases que o solicitante pode substituir como "a ser substituído".
• Não pode dizer: Afirmar explicitamente em frase declarativa ("Não se diz que …"). Não terminar com notas pequenas ou "pode ser que …". Pelo menos: mecanismo / identificação (coisas que o julgamento manteve como justapostas são chamadas de mesma coisa) / julgamento de quantidade (diferença menor que a faixa de erro) / leitura fora da faixa de validade do instrumento / lado não lido (ex.: lado do prompt) / generalizar "apenas" a partir de um exemplo / contar linhas não independentes como independentes.

Palavras proibidas no texto e roteiro: "o modelo pensou, hesitou, percebeu, sabia, no fundo sabia", "viu-se a mente da IA", "descobriu a mentira" e exageros similares. Escrever na figura que "os ranks da lens são leituras da lens, não um mapa do interior do modelo".

Mostrar a etiqueta de limitação em toda a tela do capítulo (uma linha sob a moldura + etiqueta de identificação no canto superior direito): faixa de validade, apenas descritivo, não identifica, lado não lido, n. Limitações que não aparecem na captura são o mesmo que não existir. Mas verificar se a limitação realmente se aplica aos dados daquela tela antes de colocá-la. Não copiar exemplos de frases (references/wording.md) para todos os capítulos sem verificação. Ex.: "Todas as posições estão fora da faixa de ajuste do instrumento" deve ser verificado posição a posição (no modelo, algumas linhas de uma condição estavam fora, mas outras linhas de outra condição, com prompt mais curto, estavam dentro). Se o escopo de aplicação variar dentro do capítulo, separar as etiquetas por linha.

→ Exemplos de frases e lista de termos proibidos em references/wording.md.

4. Padrões de apresentação (que funcionaram nas versões v1 a v5)

• Entrada pela cena: O primeiro capítulo mostra "o momento do que aconteceu" em uma única imagem (ex.: palavras intermediárias flutuam sobre o prompt antes de escrever a resposta, o quadro de respostas ainda está vazio). A auditoria numérica vem depois.
• Três eixos do sólido: Horizontal = posição (token sendo escrito) · Vertical = camada · Profundidade = rank do instrumento (primeiro lugar na frente, escala logarítmica, névoa além do limite superior). A faixa de controle é uma placa espessa; fora da faixa, cinza com "fora do controle · referência".
• Colocar sucesso e falha lado a lado: Posicionar os dois sólidos em uma única projeção, uma única câmera, escala comum. Girar um faz o outro girar também. Vídeo: lado a lado / desk e telefone: empilhados verticalmente (para preservar o tamanho mínimo da letra do cartão).
• Declarar o alinhamento: Para duas linhas com saídas diferentes, especificar onde foram alinhadas (bifurcação / palavra-chave / cabeçalho da coluna). Se a distância do ponto de alinhamento até a palavra-chave for diferente, escrever "+1 token / +3 token". Colocar lado a lado visualizações alinhadas pela distância (small multiples alinhados pela posição k da palavra-chave).
• Desenhar partes de comprimento zero com moldura: Para partes presentes apenas em um dos lados (ex.: campo de raciocínio token / 0 token), erguer molduras da mesma largura em ambos os lados; de um lado, moldura vazia tracejada. Apenas espaço em branco parece um erro de desenho e será questionado.
• Prenúncio e eco: Se o instrumento destaca palavras "a serem escritas" ou "escritas imediatamente antes", marcar essas posições (F / E) com um indicador separado, mostrando-as separadamente das posições silenciosas.
• Não preencher o que não está nos dados: Se os dados são apenas agregados e não têm posições por linha, a cena de entrada deve ser rotulada como "diagrama esquemático (não é uma linha real)". Não desenhar estados intermediários não registrados (ex.: entre 3 unidades e 1 unidade, não inserir 2 unidades nem a ordem em que desaparecem uma a uma). Para intervalos de registro (ex.: a cada 2 minutos), escrever momentos fora do intervalo como "em algum lugar entre" com uma faixa de largura.
• Decidir nomes em um único local: Nomes de posições, linhas, faces (ex.: "bifurcação", "posição alinhada") são definidos em um helper ou config. Todos os textos da tela usam o mesmo nome para a mesma coisa. Adicionar verificação que varre se nomes antigos permanecem (§5).
• Um significado por cor: Manter as cores que já têm significado (ex.: laranja = par He/Hi · azul = par apex). Não adicionar novas cores. Se for necessário adicionar cor para elementos não-dados (ex.: ilustração de camada interna), verificar com um validador de dataviz se a nova cor tem ΔE ≥ 15 em modo normal e ΔE ≥ 8 em modo CVD, tanto no fundo claro quanto escuro. Não usar personagens de terceiros, imagens ou fontes externas.

5. Verificações (passar todas antes de capturar)

• Console limpo (4 variantes de página · desk · telefone · vídeo · reduced motion · marimo · JupyterLab). Avisos de extensões não relacionadas à figura são registrados e distinguidos.
• Robustez: Exceção 0 em todos os estados × todas as linhas × algumas camadas.
• Conferência numérica: âncoras de check_claims.py (arquivo, chave, valor esperado) todas iguais · nenhuma faltando. N/N valores de verificação.
• Botões de capítulo: Clicar de verdade em cada botão leva ao primeiro estado do capítulo; verificar aparência selecionada, hash, rótulo (ja / en).
• Tamanho da letra: Medir o pixel mínimo do cartão em cada moldura de captura (referência: vídeo ≥ 10 px · desk ≥ 10 px · telefone ≥ 9.5 px). Um cartão ilegível é o mesmo que não existir.
• Estouro: Zero caracteres fora do viewBox.
• Cercas de publicação: Zero ocorrências de termos internos (§8) nos arquivos do corpo principal (contar com grep).
• Varredura de nomes: Varrer o texto de todos os estados × ja / en das páginas. Zero ocorrências de nomes antigos ou contextos proibidos. Incluir controle positivo da varredura (deve detectar se uma página intencionalmente contém texto antigo).
• Nota das ferramentas: O pixel mínimo do cartão no telefone só atingiu 9.5 px após reduzir o viewBox (aumentando a letra) e reorganizar o texto dos quatro cantos do kit em colunas verticais (o valor inicial no modelo era 2.7 px). ?video=1 oculta os botões de capítulo, então o teste de clique deve ser feito em desk e telefone.

→ references/checks-and-captures.md.

6. Capturas e roteiro

• Cada estado: 1920 × 1080 (para vídeo · exatamente esse tamanho) + desk (escuro / claro) + telefone. Estados que mostram um momento usam dois quadros (antes/depois, ex.: posição 24 → 25).
• SCRIPT_yukkuri.md: Diálogo (A = ouvinte / B = explicador) com ≤ 150 segundos · dica do estado a mostrar para cada linha · primeiros 10 segundos são a cena. Não usar nomes ou imagens de personagens reais.

7. Uma rodada de co-leitura (o principal uso desta figuração)

Quando uma pessoa que vê a figura faz uma pergunta (ex.: "De onde vem o He?"), transformá-la em um cartão e respondê-la. Procedimento: 0. Confirmar as palavras da pergunta: Verificar se a posição, linha e palavra a que a pergunta se refere são determinados de forma única na figura. Se o nome usado na figura é inconsistente (ex.: a mesma posição é chamada de "bifurcação" em uma tela e "um passo antes da bifurcação" em outra), antes de ler os números, pedir ao solicitante que esclareça em uma pergunta, e corrigir a inconsistência de nomes na figura.

1. Levantar candidatos (leitura, L3): Duas ou três explicações que possam responder à pergunta. Marcar cada uma com três indicadores: (a) depende ou não do instrumento (lens) / (b) a quantidade está no persist (dados salvos) ou requer uma nova forward pass ou uma nova geração ("não está no persist" não significa "a quantidade não existe" — ex.: o rank da saída do próprio modelo existe em todas as posições, mas apenas o rank dos tokens escritos foi salvo) / (c) toca nas cercas do artigo (ex.: não conectar predicados a camadas fora da faixa de controle). Colocar primeiro os candidatos "independente de lens · está no persist", depois os que requerem forward, depois os dependentes de lens. Remover candidatos que tocam nas cercas.
2. Congelar o cartão primeiro: Colocar PREREG (pergunta, universo, controles = incluindo controle positivo, palavras para a leitura, o que não afirmar, divulgação do que foi visto antes) e script em um único commit. Só executar --fire se não estiver dirty. Congelar antes de ver os valores.
3. Ler → RESULT: Números são cópia da saída (L1) · leitura é L3 · o que não afirmar permanece como no PREREG.
4. Se o controle falhar, parar: Parar sem escrever os dados da figura, diagnosticar a causa apenas com o texto, e religar a versão corrigida como um novo cartão (não alterar a definição do cartão após a execução). Ex.: a decodificação caractere por caractere de caracteres multibyte quebrou em U+FFFD, desalinhando posição e texto → controle C2 capturou → novo cartão com alinhamento por bytes. Registrar como exemplo concreto de que "a leitura da IA também precisa de controles".
5. Retornar à figura como um estado: "Uma pergunta surge da figura, um cartão responde" = ver a figura → pergunta humana → candidatos da IA → congelar cartão e ler → resposta e o que não pode ser dito → próxima pergunta.

→ references/coread-loop.md (modelo de cartão, conceito de controles).

8. Camadas internas (analogias, jargão interno)

Se for desejável incluir analogias internas do laboratório (ex.: nomes internos, mascotes) na figura, fazê-lo como camadas ocultas: colocar em arquivos separados (*_layer.js / *.css / README_internal.md). O corpo principal apenas "se existir, lê; se não existir, não faz nada". A ativação/desativação é feita por comando oculto (sequência de teclas) + flag na URL + trait do widget. Padrão: desligado · apenas na página em japonês · não faz nada na página em inglês. Quando a camada está ligada, exibir "camada interna · não divulgar externamente" no canto superior direito. Incluir na verificação que os arquivos do corpo principal têm zero ocorrências de jargão interno (para que a figuração não seja removida do pacote de publicação). Desenhar as próprias ilustrações das analogias. Deixar claro, mesmo dentro da camada, que a analogia "não pode ser dita" como afirmação sobre o mecanismo.

9. Revisão e versionamento

• Separar pastas por versão (_v1…_vN), não sobrescrever versões anteriores. Pequenas correções são vN.1, vN.2 … com notas sobre "o que foi corrigido · apontamento de quem".
• A revisão é feita por um leitor de um modelo de família diferente do criador, recebendo apenas o arquivo de critérios, as capturas e CLAIMS / NOTES / README (não mostrar os julgamentos uns dos outros · não permitir adivinhar quem é o criador). A bitola é E1 / E2 / E4 (+ E3 como referência). O modelo de critérios está em references/judging.md.

10. Publicação (ao anexar a um artigo)

• A página funcional é mostrada via GitHub Pages (site estático). A mesma release do repositório é congelada com DOI no Zenodo (Zenodo não renderiza HTML, mas o pacote completo pode ser baixado e funciona com file://). No artigo, escrever ambos.
• Remover as camadas internas (§8) do pacote de publicação. Manter a atribuição MIT do Anatomy (Copyright (c) 2026 Ryan) no README e no rodapé da página.
• Incluir este SKILL.md no pacote: mesmo que a reprodução completa não seja possível, mostra o procedimento (prompt) usado para criar a figuração.
• Incluir md5 no MANIFEST. → references/publishing.md.