Revisão de SEO em HTML
Visão Geral
Produza uma lista acionável de descobertas classificadas por severidade para um ou mais arquivos HTML estáticos. A habilidade inclui um parser HTML baseado apenas na biblioteca padrão que extrai todos os sinais relevantes de SEO em um único documento JSON, uma rubrica abrangente e um modelo de relatório de descobertas — juntos, eles permitem que uma auditoria seja executada com saída previsível todas as vezes.
Quando usar
Use quando a entrada for um ou mais arquivos .html estáticos (ou um diretório deles) e o usuário quiser descobertas de SEO on-page nas quais possa agir. Gatilhos incluem "revisão de SEO", "auditoria de SEO", "verificar SEO neste HTML", "revisar meta tags nesta página", "auditar SEO on-page".
Não use quando:
- O artefato for fonte de um gerador de site estático (Jekyll/Hugo/Astro/Eleventy/Next.js). Esses precisam de revisão ciente da fonte; adie para uma futura habilidade
ssg-seo-review. - O usuário quiser métricas de desempenho ao vivo (LCP, CLS, INP). Apenas o HTML não pode produzi-las; recomende Lighthouse ou PageSpeed Insights.
- O usuário quiser backlinks, autoridade de domínio ou outras análises off-page. Isso requer ferramentas de terceiros (Ahrefs, SEMrush, etc.).
Fluxo de Trabalho
1. Extrair sinais
Execute o parser no alvo. Ele aceita um único arquivo ou um diretório (recursivo *.html):
python3 scripts/extract_seo_signals.py <caminho> --pretty
A saída é um documento JSON com as seguintes chaves de nível superior: lang, title, meta, links, scripts, headings, images, links_audit, body_word_count. Cada elemento carrega um número de line para citação nas descobertas.
Para um diretório, a saída é {"files": [<objeto por arquivo>]}.
O script usa apenas a biblioteca padrão do Python — sem necessidade de pip install. Se a análise de um arquivo específico falhar, o resultado para esse arquivo conterá um campo error e a auditoria continuará para o restante.
2. Mapear sinais para a rubrica
Carregue references/seo-checklist.md. Percorra cada seção em ordem e verifique o caminho JSON correspondente. A rubrica lista explicitamente o caminho a inspecionar para cada verificação (por exemplo, images.missing_alt, meta.description.length, scripts.render_blocking_candidates).
Para cada verificação com falha, registre:
- A severidade (P0/P1/P2/P3) da rubrica.
- O número da linha da saída JSON.
- A marcação exata ou valor do atributo citado do arquivo (releia o arquivo com o número da linha para citar textualmente — nunca parafraseie).
- A correção, escrita como um diff concreto de antes/depois quando a alteração for mecânica.
3. Verificar cada descoberta antes de relatar
Antes de escrever uma descoberta, confirme o problema mecanicamente:
- Uma alegação de que um atributo está "ausente" deve vir da saída estruturada do parser, não de uma leitura superficial do HTML.
- Uma alegação de que um valor é "muito curto/longo" deve citar a contagem real de caracteres do JSON.
- A marcação citada deve ser exata; se uma citação não puder ser reproduzida caractere por caractere do arquivo, descarte-a.
Isso protege contra a falha mais comum de revisão: fabricar um problema que não existe.
4. Produzir o relatório de descobertas
Use assets/findings-template.md como estrutura. Preencha:
- Parágrafo de resumo com veredito geral e contagens de severidade.
- Um bloco por descoberta, ordenado por severidade (P0 → P3) e depois pela ordem dos arquivos.
- Uma seção opcional "Ganhos rápidos" quando o número de descobertas exceder ~10 — escolha as 3-5 correções de maior impacto.
- Uma seção "Itens fora do escopo observados" listando qualquer coisa que o usuário deva acompanhar com ferramentas externas (Lighthouse para CWV real, curl para resolução de canônica, etc.).
Se a auditoria cobrir vários arquivos, produza um relatório cobrindo todos eles, com descobertas agrupadas por arquivo dentro de cada nível de severidade — não um relatório por arquivo.
5. Pular graciosamente
Se uma verificação exigir informações que o parser não pode produzir (por exemplo, "esta URL canônica está servindo um código 200?"), não adivinhe. Anote na seção "Itens fora do escopo" do relatório e siga em frente.
Referência
scripts/extract_seo_signals.py— Parser HTML. Apenas stdlib. Produz JSON estruturado com números de linha.references/seo-checklist.md— Rubrica completa, organizada por categoria, com níveis de severidade e caminhos JSON para cada verificação.assets/findings-template.md— Formato de saída para o relatório de auditoria.