baratihd/skills

Nota de Versão do Treatment Backend

Gere uma nota de versão precisa e auditável em inglês a partir de evidências reais do repositório ao promover uma branch de origem para uma branch de destino, especialmente stage ou production. Após escrever a nota de versão, produza um resumo separado em persa (headline) apenas na conversa. Nunca anexe, incorpore ou escreva o resumo em persa na nota de versão ou em qualquer outro arquivo do projeto.

Contrato de execução entre agentes

• Esta skill é portátil entre Codex, OpenCode e Claude Code; nenhuma ferramenta específica de fornecedor é necessária. Leia este SKILL.md e os arquivos references/ vinculados quando invocado.
• Uma cópia canônica está armazenada em .agents/skills/treatment-backend-release-note/; .claude/skills/ e .opencode/skills/ apontam para a mesma cópia ao usar o instalador integrado. Não mantenha cópias divergentes.
• Se ferramentas ou permissões não estiverem disponíveis, relate a limitação com precisão; não invente evidências de Git ou status de versão.
• Aceite invocação em linguagem natural, ou $treatment-backend-release-note no Codex, /treatment-backend-release-note no Claude Code e em configurações suportadas do OpenCode. Todas as invocações seguem exatamente o mesmo fluxo de trabalho e política de saída.

Entradas e escopo

• Obrigatório: source_branch, target_branch (destino padrão apenas se o usuário estabelecer explicitamente uma convenção de projeto; caso contrário, pergunte quando genuinamente indisponível).
• Opcional: versão da versão, janela de implantação, referências de ticket, nome do arquivo de saída (armazenado em docs/releases/), método de implantação, proprietário.
• Detecte remotos e valide refs, condição da árvore de trabalho e raiz do repositório antes de coletar alterações. Não mude branches, faça pull, fetch, commit, merge, tag, implante ou modifique código do aplicativo sem autorização explícita.
• Se origem/destino não forem especificados, tente inferi-los a partir do contexto claro (ex.: o usuário diz "faça release da develop para stage"); caso contrário, pergunte. Nunca assuma silenciosamente que a branch atual é a origem.
• Ambos os refs podem ser branches locais ou branches de rastreamento remoto; especifique exatamente quais refs resolvidos e hashes de commit foram analisados.
• Interprete o relatório como alterações introduzidas pela origem no destino, não tudo o que foi commitado na branch de origem.

Fluxo de trabalho

1. Pré-verificação e evidências do Git

A partir da raiz do repositório, inspecione estes comandos (adapte os nomes dos refs com segurança; não interpole argumentos de shell não confiáveis):

git status --short
git remote -v
git branch -a
git rev-parse --verify <source>^{commit}
git rev-parse --verify <target>^{commit}
git merge-base <target> <source>
git log --date=short --format='%h %ad %s' <target>..<source>
git diff --stat <target>...<source>
git diff --name-status <target>...<source>
git diff <target>...<source> -- <relevant-paths>

target..source identifica commits não alcançáveis a partir do destino. target...source em git diff compara a base de merge com a origem, aproximando as alterações propostas pela branch de origem. Eles podem não ser iguais ao diff de merge resultante exato para branches divergentes, cherry-picks ou rebases. Para uma versão proposta, inspecione ambas as perspectivas de commit e diff, identifique anomalias e, se necessário, use uma worktree descartável/merge temporário somente com autorização. Não afirme um resultado mesclado definitivo a partir de um diff de três pontos não verificado. Para uma versão já concluída, prefira o commit de merge registrado, tag, SHA implantado ou refs reais de antes/depois da implantação, se disponíveis.

Revise arquivos de origem significativos, migrações, configuração, esquemas de API, serializadores, permissões, tarefas em segundo plano, integrações, testes e manifestos de implantação; evite confiar apenas nos assuntos dos commits. Exclua arquivos gerados/de ruído da narrativa quando apropriado, mas não oculte migrações geradas impactantes ou alterações em lockfile. Verifique alterações com efeitos de negócios que abrangem vários commits. Agrupe por capacidade de negócio em vez de listar cada arquivo alterado. Vincule código a tickets/PRs quando demonstrável.

2. Classifique alterações e impacto

Separe e descreva:

1. Alterações de negócio — fluxos de trabalho novos ou modificados, regras de elegibilidade, cobertura, processamento de despesas/reivindicações, relatórios, notificações e comportamento observável. Escreva apenas quando suportado por código, testes ou contexto de produto fornecido pelo usuário; rotule claramente inferência ou confirmação ausente.
2. Alterações técnicas — APIs, modelos/migrações Django, jobs/Celery, banco de dados/índices, integrações externas, configurações, segurança/permissões, confiabilidade, desempenho, observabilidade, CI/CD e refatoração.
3. Compatibilidade e consumidores — endpoints/métodos REST, campos de requisição/resposta, códigos de status, autenticação, clientes web/mobile, chamadores internos, workers, sistemas de terceiros, banco de dados e eventos. Informe Breaking change: Sim / Não / Desconhecido com evidências. Distinga compatibilidade de API de compatibilidade de implantação/dados. Explique ações necessárias do consumidor e ordem de implantação quando relevante.
4. Validação e rastreabilidade — refs exatos de origem/destino + SHAs, SHA base, commits notáveis, links de tickets/PRs quando encontrados, testes e seu status real observado, planos de migração, aprovadores/status se fornecidos. Não afirme que um teste passou sem executá-lo ou obter resultados de teste confiáveis.
5. Reverter / rollback — descreva etapas e pré-requisitos apropriados ao destino, com tratamento distinto para reversão de aplicação, migrações de esquema reversíveis, migrações de dados irreversíveis, jobs reproduzíveis, mensagens, idempotência e efeitos colaterais de terceiros. Sempre distinga uma reversão do Git de um rollback operacional. Nunca afirme que o rollback é seguro sem verificar migrações e efeitos colaterais.

Revise a lista de verificação completa em references/review-checklist.md.

3. Componha e salve a nota de versão em inglês

Siga references/release-note-template.md. Use inglês para todo o conteúdo salvo na nota de versão, incluindo cabeçalhos. Mantenha conciso, mas informativo e apropriado para revisão de engenharia e negócios. Use "Não verificado", "Desconhecido" ou "Requer confirmação" em vez de inventar detalhes.

O diretório de saída canônico do projeto é docs/releases/. Salve cada nota de versão lá; não crie um diretório release-notes/ na raiz. A saída padrão é docs/releases/YYYY-MM-DD-<source>-to-<target>.md, com barras de branch substituídas por hífens. Honre um nome de arquivo explicitamente solicitado, mantendo-o em docs/releases/. Evite sobrescrever uma nota de versão existente. Se o destino existir, escolha um nome de arquivo único ou busque aprovação explícita para substituição. Use a data de geração apenas como data de documentação, não uma data de implantação fictícia. A nota de versão é uma versão proposta até que a implantação seja verificada.

Após salvar, leia o arquivo de volta e valide: direção da branch e identidades de commit, alterações de negócio/técnicas, compatibilidade, verificação, rastreabilidade, rollback e ausência de resumo em persa. Não faça auto-stage ou commit da nota de versão a menos que solicitado. Relate o caminho relativo salvo.

4. Resumo em persa apenas no chat (obrigatório)

Apenas após salvar e validar com sucesso, apresente um breve resumo em formato de headline em persa na resposta final do agente. Foco em resultados legíveis para negócios, riscos significativos, ações necessárias do consumidor/implantação e prontidão/desconhecidos. Normalmente, 3 a 7 marcadores curtos, sem detalhes de implementação de baixo nível, a menos que necessário. Exemplo de formato:

خلاصه برای ارائه به بیزینس (فقط در پاسخ Agent، خارج از فایل):
- بهبود فرآیند ...
- تغییر در رفتار ...
- نیاز به هماهنگی با ...
- وضعیت اعتبارسنجی: ...
- ریسک و برنامه بازگشت: ...

Inclua apenas declarações estabelecidas durante a revisão. Não salve este resumo em nenhum arquivo, log, mensagem de commit ou apêndice da nota de versão. Se a gravação falhar, não afirme que a nota de versão foi registrada; explique o obstáculo e, se útil, forneça um resumo provisório claramente marcado como provisório.

Portões de qualidade

• Baseie cada alteração e afirmação no diff inspecionado, testes, histórico do Git ou contexto de versão fornecido explicitamente; distinga fatos verificados de inferências.
• Não imprima segredos, tokens, senhas, dados de clientes privados ou credenciais brutas encontradas em diffs. Redija exemplos.
• Não equacione código commitado com funcionalidade implantada, e não equacione um teste não executado com um teste aprovado.
• Quando uma branch incluir alterações não relacionadas, documente o escopo e o risco em vez de descartar silenciosamente modificações importantes.
• Use Nenhum identificado explícito somente após verificação; caso contrário, use Desconhecido / Não verificado.
• Nunca execute migrações, manipule dados de produção ou realize rollback como parte da documentação dos mesmos.