d3group/d3-explainer

D3 Explainer (HTML interativo, para os próprios autores)

<skill-dir> nesta skill significa o diretório base da própria skill, que o Claude Code mostra quando a skill é carregada (instalada como um plugin: ${CLAUDE_PLUGIN_ROOT}/skills/d3-explainer; copiada manualmente: ~/.claude/skills/d3-explainer). Substitua o caminho real em cada comando. <wording-dir> significa <skill-dir>/../d3-scientific-wording, a skill de redação compartilhada que todo plugin D3 incorpora.

Um arquivo HTML offline que explica um projeto de pesquisa para as pessoas que o estão escrevendo: qual é a pergunta, qual lacuna ele fecha, como a ideia central funciona, como cada derivação é feita e porquê, onde tudo reside no código, o que as evidências mostram e o que ainda está em aberto. Figuras interativas carregam a intuição; o texto permanece próximo das fontes e assim o declara.

O leitor é o autor e seus coautores. Isso decide quase tudo abaixo:

• Eles conhecem a área. Pule o conhecimento básico de livros-texto, a menos que suas anotações mostrem que é um ponto sensível.
• Eles querem entender, então a honestidade supera o polimento: suposições, divergências entre artigo e código e perguntas em aberto têm sua própria seção, e interpretações são marcadas como tal.
• Eles verificarão as afirmações em relação aos seus próprios arquivos, então cada afirmação substantiva aponta para sua fonte, e a compilação verifica se o ponteiro existe.
• Detalhar é bom, ser exaustivo não é. Aprofundamento que apenas alguns leitores desejam vai para blocos recolhidos. "Cada detalhe" acontece apenas quando o usuário solicita, e então apenas para a parte que ele nomeia.

Todo Python executa através de uv (uv run, uv run --with <pkg>); nunca pip, nunca instalações globais.

Arquivos de referência (carregar sob demanda)

Arquivo	Carregar quando
references/scanning.md	Fase 1: lendo um repositório com orçamento de tokens, níveis de entrada, vault / recall / NotebookLM, explicadores anteriores
references/content-design.md	Fases 2 e 3: espinha dorsal das seções, orçamentos de profundidade, como apresentar a lacuna e as derivações, inventário honesto, o que é específico para a redação do explicador (as próprias regras: d3-scientific-wording)
references/components.md	Fase 3: o vocabulário HTML, chips de fonte, diretivas de compilação, explainer.toml, a API JavaScript D3X
references/visualization.md	Fases 2 e 3: projetando figuras interativas que ensinam; catálogo de padrões; armadilhas
references/review.md	Fase 4: os dois prompts de revisão, regras de token, o ciclo
assets/example/	Um pequeno repositório com um explicador finalizado. Leia assets/example/explainer/sections/*.html uma vez para obter padrões de funcionamento de cada componente. Nunca copie para um projeto de usuário.

Passo 0: perguntar uma vez

A menos que o usuário já tenha dito, pergunte tudo em uma única mensagem e não pergunte novamente:

Escopo. O projeto inteiro ou uma parte (um modelo, uma derivação, um pipeline)? Profundidade. focus (uma ideia ou uma derivação: 1 a 3 seções, uma ou duas figuras, cerca de 5 minutos), overview (4 a 6 seções, cerca de 10 a 15 minutos de leitura), standard (padrão: 7 a 10 seções, 4 a 8 figuras interativas, 1 a 3 derivações, 20 a 35 minutos) ou deep (até 14 seções). "Deep on X" significa standard mais uma seção de aprofundamento em X. Revisão. light: verificações automatizadas mais minhas próprias passagens de números, quase nenhum token extra. single: um agente revisor cobre tanto a fidelidade quanto as figuras, uma rodada, cerca de 50 a 70 mil tokens. standard: dois agentes revisores em paralelo (fidelidade às suas fontes; figuras e interação), uma rodada, cerca de 100 a 150 mil tokens juntos. O custo de um revisor é principalmente um piso fixo e dificilmente depende do tamanho do projeto, então minha recomendação segue a profundidade: focus light, overview single, standard e deep a revisão de dois agentes. full: os dois agentes iteram até que cada pontuação seja 9 de 10, limitado a três rodadas, duas a três vezes o custo do standard. Redação. ste (padrão: Inglês Técnico Simplificado conforme ASD-STE100, no máximo 25 palavras por frase, voz ativa, um significado por palavra; mais fácil para coautores que leem inglês como segunda língua) ou standard (a redação científica do grupo sem os limites do STE).

"rápido", "sem revisão", "barato" ou "poucos tokens" significa light. "completo" significa full. "apenas esta derivação", "só explicar X", "seja curto" significam focus. "simples", "STE" ou nada dito significam redação ste; "redação normal", "estilo de artigo" ou "sem STE" significam standard. Nada dito significa profundidade standard e a revisão recomendada para essa profundidade.

Quando ninguém pode responder (uma execução em lote ou agente): assuma os padrões, decida cada ponto que esta skill perguntaria, registre cada decisão na seção 0 do brief.md e continue. O brief é então o lugar onde o autor pode ver o que foi decidido por ele.

Fluxo de trabalho

Imprima um status com timestamp de uma linha em cada limite de fase, como as outras skills D3 fazem: [HH:MM:SS] PHASE: ....

Fase 1: Mapear o projeto (ler de forma barata, na ordem correta)

uv run <skill-dir>/scripts/scan.py            # a partir da raiz do repositório; adicione --out explainer/scan.md para mantê-lo

O scan relata o nível de entrada (A: código e artigo, B: apenas artigo, C: apenas código, D: apenas PDF, E: apenas anotações), quando os documentos de orientação, o artigo e cada pasta de código foram modificados pela última vez (um CLAUDE.md desatualizado ou uma abordagem abandonada aparece aqui), o esboço do artigo com seus rótulos de equações, os maiores módulos de código com nomes de símbolos e números de linha, arquivos de resultados incorporáveis, o vault com as anotações do autor por pasta, explicadores anteriores e uma estimativa de tokens para cada documento de orientação, artigo, arquivo de seção, módulo de código e anotação. Imprima INPUT TIER: X e permita que o usuário substitua.

Em seguida, leia, nesta ordem, e pare quando o brief puder ser escrito. Detalhes e orçamentos estão em references/scanning.md.

1. Documentos de orientação (CLAUDE.md, README, especificações ou notas de análise na raiz).
2. O artigo: resumo, introdução, declaração de contribuição, em seguida, as seções de modelo e método. Folheie os resultados para os números principais.
3. Explicadores anteriores encontrados pelo scan: o esboço (scan.py --explainer <file>), em seguida, uma seção completa para tom (--section N). Eles mostram o que o autor já entende e a voz que ele gosta. Construa sobre eles; não os repita.
4. Vault: visão geral, conceito, lacuna, decisão e anotações de perguntas em aberto, escolhidas pelo título. Não o dump da literatura.
5. Código: apenas os módulos que realizam a ideia central, encontrados através do mapa de símbolos. Para uma base de código grande (mais de cerca de 40 arquivos ou 8.000 linhas), envie um subagente Explore para produzir o mapa artigo-para-código e mantenha sua conclusão, não os arquivos.

Enriquecimento opcional, oferecido apenas quando a lacuna ou o histórico do projeto é escasso no repositório: a skill recall (o que foi decidido e quando) ou NotebookLM (o que a literatura diz). Mesmo protocolo do d3-abstract. Quando o scan encontrou uma pasta de literatura, um vault com fontes importadas ou um notebook NotebookLM, ofereça na mesma pergunta um perfil de tópico do d3-scientific-wording (Passo 1b): ele mostra qual termo e ortografia a literatura usa para cada conceito, o que alimenta a tabela de notação e a folha de termos. Imprima ENRICHMENT: skipped | recall | notebooklm | both [+ wording profile].

Fase 2: Brief de conteúdo, aprovado antes de qualquer HTML

uv run <skill-dir>/scripts/init.py --depth standard --review standard   # cria ./explainer: explainer.toml, brief.md, sections/, d3x/
#   vários artigos no repositório: adicione --paper <folder>         explicador em outro local: init.py <dir> --repo <repo root>

Local de salvamento: <repo>/explainer/, na raiz do repositório externo (não dentro do submódulo do artigo: Overleaf não tem uso para ele). Confirme o local na mesma mensagem que o brief.

Preencha explainer/brief.md: o projeto em duas frases, o que o leitor deve ser capaz de fazer depois, fontes lidas e deliberadamente não lidas, a lacuna, o plano de seções, as derivações, o inventário honesto, o que foi omitido de propósito e o brief de redação sob um cabeçalho ## Wording (gênero explicador, leitores os coautores, campo, o modo de redação escolhido e uma folha de termos para os construtos e símbolos do projeto). O plano de seções tem uma linha por seção e, para cada figura interativa, sua frase de controle-para-insight: "mover X mostra que Y". Uma figura sem tal frase é decoração e é cortada aqui, não depois de construída.

Mostre o brief no chat em formato compacto e obtenha aprovação. Este é o único ponto de verificação obrigatório: custa algumas centenas de tokens e evita escrever as 6.000 palavras erradas. Não escreva seções antes disso.

Fase 3: Escrever, uma seção de cada vez

Invoque d3-scientific-wording antes da primeira seção (Ferramenta Skill: d3-scientific-wording:d3-scientific-wording; quando não estiver listada, leia <wording-dir>/SKILL.md), com o brief do brief.md. No modo ste, leia também <wording-dir>/references/ste.md. Carregue references/components.md e references/visualization.md, e folheie as seções de exemplo uma vez; elas estão escritas em STE.

• Um arquivo por seção: explainer/sections/NN-slug.html, exatamente um <section id=... data-nav=... data-kicker=...> cada. A compilação as numera e cria a navegação.
• Compile após cada seção, para que os erros permaneçam locais: uv run explainer/d3x/build.py --draft (marcadores TODO e links para seções ainda não escritas apenas avisam)
• Ordem dentro de uma seção de ideia central: frase simples, figura interativa, declaração formal, derivação, onde reside no código. Intuição primeiro, álgebra depois.
• Deixe o repositório falar em vez de redigitá-lo. <div class="eq" data-label="eq:prob"></div> puxa a equação do .tex do artigo (com seu número, se um .aux existir). <pre class="code" data-src="src/model.py" data-lines="88-104"></pre> puxa as linhas reais. Ambos são mais baratos do que digitar e não podem divergir da fonte.
• Aponte para fontes com chips: [[paper:eq:prob]], [[code:src/model.py:88 def solve]], [[vault:Note name]], [[result:results/table.csv]] e [[reading]] para sua própria interpretação. A compilação falha em um arquivo, linha, símbolo, rótulo ou anotação que não existe; um chip de vault apenas avisa enquanto nenhum vault estiver configurado em explainer.toml. Um chip com falha é uma descoberta sobre sua compreensão: corrija a afirmação, não exclua o chip.
• Figuras interativas mostram, em ordem de preferência: os arquivos de resultado do repositório; números computados pelo próprio código do repositório em uma grade (um pequeno explainer/data/make_data.py, veja visualization.md); ou a fórmula real reimplementada em escala de brinquedo no navegador, declarada toy: true, que coloca um distintivo visível "brinquedo ilustrativo". Os padrões situam-se na configuração do artigo. Os números são incorporados de arquivos, nunca digitados de memória.
• Toda legenda de figura começa com {fig} (a compilação numera as figuras; refira-se a uma como {fig:figure-id}) e diz o que tentar e o que notar.

Fase 4: Verificar

uv run explainer/d3x/build.py                  # sem --draft: marcadores TODO agora falham; imprime palavras por seção contra o orçamento de profundidade
uv run explainer/d3x/check.py --shots          # navegador headless: move cada controle, arrasta cada alça, percorre cada derivação

check.py deve terminar com 0 error(s). Em seguida, verifique a redação das seções (remova --ste no modo standard); corrija cada erro e decida cada aviso:

uv run <wording-dir>/scripts/check_wording.py explainer/sections/*.html --genre explainer --ste

Isso captura o que a leitura da fonte não pode: NaN em um caminho, um controle que não muda nada, uma fórmula que MathJax não consegue renderizar, um rótulo cortado em um extremo de controle deslizante, estouro de página na largura do telefone. Sua primeira execução em uma máquina pode pedir um navegador uma vez: uv run --with playwright playwright install chromium (ele recai para um Chrome ou Edge instalado).

Olhe para duas ou três das capturas de tela em explainer/review/shots/ você mesmo. Em seguida, revise na profundidade escolhida; prompts e regras de token estão em references/review.md:

• single: um revisor somente leitura com o prompt mesclado de references/review.md, lendo ambos os pacotes, check.md e as capturas de tela em uma rodada. Em seguida, verifique e aplique como abaixo.
• light: sem agentes revisores. Faça você mesmo uma passagem de números: cada número no texto, os tiles de KPI e os padrões das figuras em relação ao artigo ou arquivo de resultado citado. Depois pare.
• standard: dois revisores somente leitura em paralelo, uma rodada. Cada compilação escreve dois pacotes em explainer/review/: fidelity-packet.md (o texto do explicador com números de linha, os passos da derivação com suas razões e, para cada chip, a equação citada ou linhas de código como evidência) e figures-packet.md (legenda e script de cada figura). O revisor de fidelidade verifica as derivações, números, afirmações de lacuna e a redação (a leitura a frio e as regras do d3-scientific-wording) do primeiro; o revisor de experiência verifica que cada figura ensina sua frase de controle-para-insight do segundo, além de check.md e as capturas de tela. Nenhum precisa percorrer o repositório, o que mantém a revisão acessível. Não edite os arquivos de seção enquanto eles executam. Em seguida, verifique cada bloqueador e ponto importante você mesmo, aplique-os, recompile, execute check.py novamente. Uma segunda olhada acontece apenas para um bloqueador, apenas pelo revisor que o levantou, apenas nos arquivos alterados.
• full: os mesmos dois revisores, em loop até que cada categoria seja 9 ou melhor, limitado a três rodadas; em seguida, entregue os pontos restantes ao usuário.

Fase 5: Entregar

Forneça o caminho explainer/dist/<name>.html (um arquivo, funciona offline, seguro para e-mail), a profundidade de revisão usada e a tabela de descobertas mesclada com o que foi corrigido. Mencione: n abre a gaveta de notação, as derivações progridem com "Próximo passo", os chips linkam para permalinks do GitHub no commit compilado quando o remoto está no GitHub. Se o repositório tiver um vault, ofereça-se para colocar uma cópia do HTML nele, onde os explicadores anteriores do autor residem. Faça a pergunta da marca d'água do d3-scientific-wording (Passo 5) uma vez; em caso afirmativo, limpe explainer/sections/*.html (nunca o arquivo compilado, que incorpora MathJax e fontes) e recompile. Ofereça-se para commitar o explicador e adicionar um link a ele no CLAUDE.md do repositório. Se a resposta solicitou "extrair e commitar" durante o escaneamento (Fase 1), então faça tudo sem perguntar: limpe, recompile e comite.