revisão-de-cópia-do-site

Revisão de cópia do site

Transforme um código-fonte de site em um documento que um revisor não técnico possa ler página por página e marcar, onde cada string mantém um endereço (um código Ref) para que suas edições possam ser aplicadas de volta à origem mecanicamente.

Por que foi construído assim

A cópia de um site não é prosa. São centenas de strings curtas em slots de layout fixos dentro de marcação. Então:

• Um dump de prosa com controle de alterações retorna como uma borrão de inserções que não podem ser recolocadas na marcação sem adivinhação. Daí uma linha por string, com um código Ref.
• Um revisor que transforma um título de card de 4 palavras em 12 palavras quebra o layout e não consegue ver isso do Word. Daí contagens de caracteres e orientação de tamanho em linguagem simples em linhas restritas.
• Revisores nunca veem o código. Daí cada linha dizer o que é ("Rótulo de botão", "Texto alternativo") em palavras simples, e cada seção de página dizer onde vive no site ao vivo.

O documento deve ser lido de cima para baixo por página (para que tom e narrativa possam ser julgados) enquanto mantém cada string individualmente endereçável.

Arquivos incluídos

scripts/merge_and_verify.py, scripts/build_review_docx.py, references/extraction-brief.md e assets/pages.example.json ficam ao lado deste arquivo. Se estiverem faltando (a habilidade foi instalada apenas como SKILL.md), procure por eles em ~/my-skills/website-copy-review/ ou no repositório brianitsup/website-copy-review; se nenhum estiver acessível, informe o usuário em vez de improvisar o layout do documento, pois ele não deve variar entre execuções.

Regras básicas

• Somente leitura. Nunca edite o repositório. Toda saída vai para o scratchpad, a menos que o usuário peça para colocá-la no repositório.
• Instale python-docx em um virtualenv no scratchpad, não globalmente: python3 -m venv <scratch>/venv && <scratch>/venv/bin/pip install python-docx
• Relate honestamente. Se um arquivo não pôde ser analisado ou uma verificação não pôde ser executada, diga; nunca estreite silenciosamente o escopo.
• Se o repositório tiver uma convenção de fluxo de trabalho baseada em issues (ou similar) em AGENTS.md, CLAUDE.md, PROJECT_WORKFLOW.md ou CONTRIBUTING.md, informe ao usuário que as edições retornadas e quaisquer defeitos precisarão de uma issue antes da implementação. Não abra uma sem ser solicitado.

Escala esperada: um site médio de folheto tem ~400–600 itens em 15–20 páginas, um documento de 50–60 páginas. Isso é normal; as tabelas por página mantêm a navegabilidade.

Etapa 1 — Definir escopo (pergunte uma vez, com padrões)

Pergunte estas juntas (AskUserQuestion se disponível), recomendando os padrões:

1. Qual cópia? Cópia codificada em templates/componentes apenas (padrão — o conteúdo do editor pode ser corrigido no CMS sem uma alteração de código), ou também posts/páginas criados no CMS?
2. Como os revisores marcarão as alterações? Coluna "Revisão sugerida" em branco (padrão — inequívoco e mecanicamente aplicável), ou comentários/controle de alterações do Word (natural, mas difícil de aplicar de volta).
3. Qual estado do conteúdo? Árvore de trabalho, ou produção/ao vivo? Sinalize que um banco de dados local ou snapshot de conteúdo pode estar atrasado em relação ao que está realmente publicado.

Se o usuário estiver ausente, assuma os padrões e informe no topo do relatório. As respostas vão para a página de capa (meta.scope em pages.json).

Etapa 2 — Descobrir onde a cópia mora

Não presuma uma pilha. Inspecione o repositório (package.json, manifestos de tema, configuração do framework, layout de diretório) e liste as fontes de cópia:

• No código: .hbs, JSX/TSX, Vue, Svelte, Astro, Blade, ERB, Twig, PHP themes, HTML, Markdown/MDX content files, i18n/locale JSON ou YAML.
• Fora do código: Banco de dados/API do CMS (Ghost, WordPress, Sanity, Contentful, Strapi) e configurações do site voltadas ao visitante que não estão no repositório — título do site, meta descrição, rótulos de navegação, rótulos de CTA/botão definidos no admin. Ao puxá-los, salve a exportação bruta em <scratch>/snapshots/ para que possam ser verificados como qualquer outra fonte (veja Etapa 4).

Sempre cubra estas categorias facilmente esquecidas, cada uma rotulada para que os revisores saibam o que estão vendo: texto alt (leitores de tela e mecanismos de busca o leem — nomes de parceiros/produtos devem estar corretos), aria-label, placeholders de formulário, rótulos de envio, mensagens de sucesso/erro/validação, estados vazios, páginas 404/erro, linhas de direitos autorais e rodapés legais.

Mapeie cada template de página para seu caminho de URL ao vivo (routes.yaml, roteamento baseado em arquivos, configuração de roteador, atribuições de template→página do CMS). Se um template não tiver página ou rota, diga explicitamente na nota dessa página — sua cópia é inacessível, e os revisores devem saber antes de gastar tempo com ela.

Em seguida, escreva <scratch>/pages.json a partir de assets/pages.example.json: uma entrada por página na ordem em que o documento deve apresentá-las, com key, title, url, source, note opcional, mais o bloco meta (projeto, respostas de escopo, exclusões, templates sem cópia codificada). O script de build lê isso — metadados de página nunca são codificados.

Etapa 3 — Extrair em paralelo com um contrato fixo

1. Enumere toda a superfície primeiro: cada template de página e cada componente parcial/compartilhado que essas páginas incluem (cabeçalhos, rodapés, cards, formulários de newsletter, CTAs). Parciais são o que se perde quando arquivos são divididos entre agentes.
2. Divida em grupos não sobrepostos (aproximadamente 3–6 arquivos ou ~1.500 linhas cada) e atribua cada arquivo explicitamente. Parciais compartilhados recebem sua própria entrada de página (ex.: FOOTER, NAV) com uma nota de que aparecem em todo o site, em vez de serem repetidos em cada página.
3. Inicie um subagente por grupo, em uma única rodada, em um modelo de nível médio (ex.: Sonnet): o trabalho é mecânico, mas omissões são invisíveis e fatais. Cole references/extraction-brief.md textualmente em cada prompt, seguido pela lista de arquivos desse agente, a page_key a ser usada para cada arquivo, a raiz do repositório e o caminho de saída <scratch>/extract/<group>.json.
4. Quando eles retornarem, confirme que cada arquivo enumerado aparece em alguma saída (ou foi relatado como não contendo cópia). Reatribua qualquer coisa faltante.

Colete os julgamentos relatados por cada agente; você precisará deles na Etapa 4 e no relatório final.

Etapa 4 — Mesclar e verificar independentemente (não pule)

Autoverificações do agente não são verificação. Execute:

<venv>/bin/python scripts/merge_and_verify.py \
  --extract-dir <scratch>/extract --pages <scratch>/pages.json \
  --repo <repo-root> [--snapshot-dir <scratch>/snapshots] --out <scratch>/out

Ele mescla todas as extrações na ordem de pages.json, atribui Refs PAGEKEY-NN, recalcula chars, e verifica novamente cada string contra seu arquivo de origem com três normalizações progressivamente mais flexíveis — bruto (espaço em branco colapsado), sem tags, espaços simplificados — porque cada uma pega uma coisa diferente (texto de atributo passa bruto e falha sem tags por construção; isso é esperado). Também afirma que não há Refs duplicados, nenhum texto vazio, e que cada page_key do item existe em pages.json. Saídas: items.json, copy-review-manifest.csv, verification.md.

Código de saída é não-zero enquanto algo não estiver resolvido. Para cada linha UNMATCHED, abra a origem e procure. Resíduo legítimo geralmente são blocos condicionais/de loop onde o agente gravou o texto renderizado em vez de uma substring literal — confirme que ele renderiza como gravado, então liste-o em <scratch>/accepted.json como {"REF": "motivo"} e execute novamente com --accept <scratch>/accepted.json. Corrija erros genuínos no JSON de extração (não no repositório) e execute novamente. Refs são atribuídos na mesclagem, então corrija os dados, execute novamente, depois construa.

Também faça uma verificação pontual de completude: pegue dois ou três dos arquivos mais densos e compare a contagem de itens com uma leitura rápida do arquivo. Strings faltantes não aparecem em nenhuma verificação automatizada.

Etapa 5 — Construir o documento

<venv>/bin/python scripts/build_review_docx.py \
  --pages <scratch>/pages.json --items <scratch>/out/items.json \
  --out <scratch>/out/<Project>-Website-Copy-Review.docx

O script controla o layout para que nunca varie entre execuções: A4 paisagem, margens de 1,4 cm; página de capa (escopo, o que está/não está incluído, como revisar, manter linhas sensíveis a tamanho perto de seu tamanho, não renumerar ou excluir Refs, verificar fatos — anos, números de funcionários, figuras, nomes de parceiros, títulos de cargos — com tanto cuidado quanto a redação); sumário com totais e templates vazios; uma seção por página em uma nova página; colunas Ref 2,2 / Elemento 4,3 / Cópia atual 8,4 / Revisão sugerida 8,4 / Notas 3,6 cm; linha de cabeçalho escura repetida; linhas de banner de seção em letras maiúsculas e com tom; listras zebradas; orientação de contagem de caracteres em linhas restritas; células com tom e um aviso "mantenha a parte {{…}}" em linhas dinâmicas; página de fechamento com próximos passos e uma tabela de aprovação. Ele reabre o arquivo e afirma que a contagem de linhas corresponde e as colunas de revisão/notas estão vazias.

Nunca pré-preencha "Revisão sugerida" ou "Notas". O julgamento do revisor é o ponto.

Se o usuário escolheu comentários/controle de alterações do Word na Etapa 1, ainda construa este documento (os códigos Ref são o que torna as alterações controladas rastreáveis) e informe que as edições podem precisar de correspondência manual.

Etapa 6 — Veja antes de entregar

Verificações estruturais provam que os dados estão corretos, não que leem bem. Renderize e realmente veja: a capa, uma página de configurações/navegação e a página mais densa de parágrafos longos (onde larguras falham).

soffice --headless --convert-to pdf --outdir <dir> <file>.docx
pdftoppm -png -r 80 -f <n> -l <n> <file>.pdf <prefix>

Abra os PNGs com Leitura. Se essas ferramentas estiverem faltando, diga claramente que nenhuma verificação visual ocorreu.

Etapa 7 — Relatar defeitos de origem separadamente

Ler cada linha da marcação revela bugs reais. Relate-os em uma seção separada (ou em um source-defects.md separado) — são problemas de código, não de redação. Comuns:

• Markdown literal em HTML renderizado (**negrito** aparecendo na página)
• Links âncora para IDs que não existem em lugar nenhum
• Links para seções que existem mas não contêm nada acionável
• Templates sem página/rota, então sua cópia é inacessível
• Conteúdo órfão do CMS por trás de um template personalizado que o substitui
• Valores de placeholder codificados em templates reutilizáveis

Verifique cada um você mesmo antes de relatar — grep pelo ID de destino, abra o template. Agentes exageram estes: uma "âncora quebrada" uma vez acabou sendo um destino válido cuja seção simplesmente não tinha nada para agir. Descreva o que está realmente lá, com arquivo e linha.

Etapa 8 — Entregar

Envie o .docx para o usuário. Mencione, brevemente: total de itens e páginas, as decisões de escopo tomadas, o manifesto CSV (para aplicar as edições retornadas por Ref — mantenha-o longe das mãos do revisor), qualquer resíduo de verificação que você aceitou e por quê, a lista de defeitos e a nota sobre issues primeiro se o repositório tiver essa convenção.

Aplicando revisões retornadas (quando o usuário voltar)

Leia as linhas da tabela do .docx retornado (Ref + Revisão sugerida + Notas), junte com copy-review-manifest.csv por Ref, e para cada revisão não vazia localize text em file perto de line e substitua-o. Sinalize em vez de silenciosamente cortar qualquer revisão que esteja muito acima de seu chars em uma linha restrita, e qualquer uma que remova uma expressão {{…}}. Mostre ao usuário as alterações planejadas antes de editar o repositório.