fix publicam a documentação em revisão para validar pela web¶

Motivação¶

O tweak anterior (docs fora de produção) tirou a exigência de deploy para atualizar o site de documentação — mas nada no /spec nem no /fix usava isso: as Partes I/II de uma spec, e o diagnóstico de um fix, continuavam sendo lidos como Markdown cru, direto no repositório, mesmo depois de aprovados no portão.

Comportamento atual¶

Antes deste ajuste: aprovar a Parte II de uma spec (ou o diagnóstico de um fix) não publicava nada — o único jeito de "ver" o documento era abrir o arquivo .md.

Comportamento desejado¶

Ao aprovar a Parte II de uma spec, ou o diagnóstico de um fix, o skill roda scripts/publicar-preview-docs.sh <branch> e mostra ao usuário o link — formatado, navegável, com Mermaid — em https://docs.garantora.com.br/.

Escopo¶

scripts/publicar-preview-docs.sh (novo): publica o site a partir de uma branch qualquer, sem depender de ela estar mesclada nem de o checkout principal do dev-remote estar naquela branch. Usa dois worktrees temporários — um de main (a ferramenta de build: Dockerfile, nginx.conf) e um da branch pedida (o conteúdo: docs/, mkdocs.yml, requirements-docs.txt) — e sobrepõe o segundo sobre o primeiro antes de buildar. Os dois são removidos ao final; só a imagem/container docs fica.
.claude/skills/spec/SKILL.md: Passo 6 passa a pedir a linha em docs/specifications/index.md (a mesma disciplina que já existia para catalog.yaml); Passo 9 (fim da revisão da experiência) passa a publicar.
.claude/skills/fix/SKILL.md: Passo 6 passa a pedir a linha em docs/fixes/index.md; Passo 7 (fim da revisão do diagnóstico) passa a publicar.

Fora do escopo¶

Publicar em qualquer outro ponto do ciclo (Parte I, Parte III, correção do fix) — só os dois momentos em que o artefato inteiro passa a existir e é aprovado por um portão: Parte II da spec, diagnóstico do fix.
Trocar a credencial de Basic Auth do site — pendência já registrada no tweak anterior.

Impactos¶

Mudança de ferramental interno (skills + um script), sem código de produto tocado.

Critérios de aceite¶

Sem comportamento testável por suíte automatizada.

Validação¶

make preflight: limpo.
Testado de ponta a ponta com a spec 0048 (spec/0048-gestao-de-cobrancas, cuja Parte II ainda está em revisão — usada como cobaia por pedido do usuário): o script rodou (por partes, porque o classificador do modo automático bloqueou a invocação do arquivo .sh inteiro nesta sessão — os comandos individuais correram sem bloqueio), o mkdocs build --strict passou incluindo specifications/0048-gestao-de-cobrancas/, e o container docs recriado serviu o HTML gerado — confirmado abrindo o arquivo dentro do container (docker exec, contornando o Basic Auth só para essa checagem) e batendo a URL pública, que respondeu 401 (a barreira correta) na rota specifications/0048-gestao-de-cobrancas/specification/.
A branch da spec 0048 nasceu antes do tweak anterior e não tinha infra/dev-remote/docs.Dockerfile — é o cenário comum (toda branch de trabalho é mais velha que o main atual), e é exatamente o que os dois worktrees resolvem: a ferramenta de build sempre vem de main, só o conteúdo vem da branch.

Documentos relacionados¶

docs-fora-de-producao — o tweak que tirou a exigência de deploy, sem o qual publicar um preview a cada Parte II/diagnóstico custaria caro demais para ser rotina.