document-release

Visão geral da skill document-release

Para que serve o document-release

document-release é uma skill de atualização de documentação pós-ship para manter os docs do projeto alinhados com o que realmente foi entregue. Ela lê a documentação, compara com o diff recente e ajuda a atualizar arquivos como README.md, ARCHITECTURE.md, CONTRIBUTING.md, CLAUDE.md, CHANGELOG.md e VERSION quando um release muda a história que os docs contam.

Quem deve usar

A skill document-release é ideal para technical writers, mantenedores de repositório e agentes que precisam transformar código já mergeado em documentação precisa, com menos conferência manual. Ela é especialmente útil quando o código já está pronto, mas a documentação ainda reflete o comportamento antigo.

Por que isso importa na prática

O principal trabalho aqui não é escrever genericamente; é sincronizar release. A skill é útil quando você precisa de um guia confiável de document-release que atualiza a prosa, remove TODOs obsoletos e mantém as release notes consistentes com as mudanças entregues, em vez de inventar uma narrativa nova do zero.

Como usar a skill document-release

Instale e acione da forma correta

Use o fluxo de instalação do document-release no seu ambiente de agente e chame a skill quando um PR for mergeado, o código for publicado ou alguém pedir para “atualizar a documentação” ou “sincronizar a documentação”. A skill foi pensada para ser usada depois da implementação, não durante a fase de rascunho exploratório.

Comece com as entradas certas

Prompts fortes incluem o diff entregue, os arquivos afetados, o público-alvo e quaisquer restrições do release. Um pedido fraco como “atualize a docs” obriga a skill a adivinhar; um pedido mais forte como “sincronize a documentação para a renomeação da API neste PR mergeado e mantenha o tom do changelog conciso” dá o contexto necessário para uma edição precisa.

Leia estes arquivos primeiro

Para usar document-release bem, comece por SKILL.md e depois inspecione os arquivos que ele aponta no seu repo, especialmente README.md, ARCHITECTURE.md, CONTRIBUTING.md, CLAUDE.md e quaisquer arquivos de release ou versão. Vale também conferir SKILL.md.tmpl se você quiser entender a estrutura gerada e o que deve permanecer estável entre uma atualização e outra.

Dicas de workflow que melhoram o resultado

Use a skill para responder, nesta ordem, a três perguntas: o que mudou, quais docs mencionam esse comportamento e o que precisa ser reescrito ou removido. Se o repo tiver TODOs ativos, exemplos obsoletos ou instruções versionadas, destaque isso explicitamente no prompt para que a skill document-release consiga limpar esses pontos em vez de preservá-los.

FAQ da skill document-release

O document-release serve só para releases finais?

Não. A skill document-release também se encaixa em PRs mergeados e em qualquer mudança pós-ship que faça a documentação publicada se descolar da realidade. Ela é menos útil para brainstorms antes do merge e mais útil depois que a fonte de verdade já mudou.

Em que isso é diferente de um prompt normal?

Um prompt normal pode gerar uma boa edição, mas document-release adiciona um fluxo de trabalho focado em release: ler os docs, cruzar com o diff, atualizar os arquivos afetados e manter voz e terminologia consistentes. Isso reduz a chance de publicar instruções desatualizadas ou deixar de atualizar um doc dependente.

É adequado para iniciantes?

Sim, desde que a pessoa consiga identificar o que foi entregue e quais docs precisam refletir isso. Iniciantes têm melhores resultados quando fornecem um resumo claro da mudança, o path do repo de destino e os arquivos que esperam atualizar.

Quando não devo usar?

Não use document-release quando você só precisa de um rascunho, de um anúncio de produto ou de documentação especulativa para código ainda inacabado. Também é uma escolha ruim se você não consegue acessar o histórico do repo ou os arquivos alterados, porque a skill depende de fundamentar as edições no que realmente mudou.

Como melhorar a skill document-release

Dê um briefing de release mais preciso

O maior ganho de qualidade vem de nomear exatamente o comportamento entregue, os docs impactados e o tom que você quer preservar. Por exemplo: “Atualize a documentação para o novo fluxo de auth, remova etapas de setup desatualizadas, mantenha o changelog factual e não altere as notas de arquitetura fora da seção impactada.”

Torne visíveis os modos de falha mais comuns

O document-release funciona melhor quando você o avisa sobre exemplos obsoletos, comandos renomeados, cross-references quebradas ou strings de versão que precisam ser atualizadas em conjunto. Se você sabe que um doc é a fonte autoritativa e os outros são derivados, diga isso; assim você evita reescritas desnecessárias e mantém a skill document-release focada.

Itere depois da primeira passada

Revise a primeira saída procurando três coisas: links faltando, screenshots ou samples de código desatualizados e desvio de terminologia entre arquivos. Depois, devolva apenas as lacunas que encontrou; isso ajuda a próxima passada a refinar o resultado de instalação e uso do document-release sem reeditar seções estáveis.

Use a skill como checklist de release

Para document-release em Technical Writing, trate a skill como uma etapa de QA pós-ship: confirme que os docs correspondem ao comportamento entregue, remova TODOs mortos e verifique instruções versionadas. As melhores entradas para o guia de document-release são específicas o bastante para que o modelo consiga reconciliar o diff com o repo em vez de reescrever tudo de forma genérica.