Narrador de Mensagens de Commit

Transforma diffs brutos do git e descrições de alterações em mensagens de commit claras e orientadas por histórias, que seguem a especificação Conventional Commits. Em vez de "atualizar arquivo.js", você obtém mensagens que comunicam intenção, contexto e impacto.

Quando Usar Esta Habilidade

• O usuário diz "escreva uma mensagem de commit", "me ajude a commitar" ou "gere um commit"
• O usuário cola um diff do git ou descreve alterações de código
• O usuário diz "como devo commitar isso?" ou "resuma meu diff"
• O usuário quer um histórico de commits melhor para sua equipe ou projeto de código aberto
• O usuário está preparando um pull request e quer mensagens de commit significativas

Pré-requisitos

Tenha pelo menos um dos seguintes itens prontos:

• Saída de git diff ou git diff --staged
• Uma descrição do que você alterou e por quê
• Uma lista de arquivos modificados

Como Funciona

Etapa 1: Reunir o Contexto da Alteração

Pergunte ao usuário (ou infira do diff) sobre:

1. O que mudou — arquivos, funções, lógica afetada
2. Por que mudou — correção de bug, novo recurso, refatoração, desempenho, etc.
3. Quem/o que desencadeou — número do problema, solicitação do usuário, débito técnico, etc.

Se o usuário fornecer um git diff bruto, extraia esse contexto automaticamente do diff.

Etapa 2: Identificar o Tipo de Commit

Mapeie a alteração para um tipo do Conventional Commits usando este guia:

Veja references/conventional-commits-guide.md para exemplos detalhados.

Etapa 3: Escrever a Mensagem de Commit

Siga esta estrutura:

<type>(<optional scope>): <short imperative summary>

<body — the story: why this change was made, what problem it solves>

<footer — issue refs, breaking change notices>

Regras para Cada Parte

Linha de assunto (primeira linha):

• Use o modo imperativo: "adicionar", "corrigir", "remover" — não "adicionado" ou "corrige"
• Máximo de 72 caracteres
• Sem ponto no final
• Minúsculas após os dois pontos

Corpo (a história):

• Explique o porquê, não o o quê (o diff já mostra o quê)
• Descreva o problema que existia antes desta alteração
• Mencione quaisquer alternativas consideradas, se relevante
• Mantenha as linhas com menos de 100 caracteres
• Separe do assunto com uma linha em branco

Rodapé:

• Referencie problemas: Closes #123, Fixes #456, Refs #789
• Marque alterações que quebram compatibilidade: BREAKING CHANGE: <description>

Etapa 4: Gerar Saída

Produza a mensagem de commit em um bloco de código copiável, seguido por uma explicação em inglês simples de uma linha da história que você contou.

Exemplo de saída:

fix(auth): prevent token refresh loop on expired sessions

When a user's session expired mid-request, the auth middleware was
triggering a token refresh, which itself failed validation and triggered
another refresh — causing an infinite retry loop that crashed the app.

This adds a recursion guard flag that aborts the refresh cycle if a
refresh is already in progress, returning a clean 401 instead.

Closes #312

História contada: Um loop infinito silencioso ao expirar a sessão estava travando o aplicativo; isso interrompe o ciclo mais cedo e retorna um erro limpo.

Múltiplos Commits de Um Único Diff

Se o diff contiver alterações logicamente separadas, divida-as em várias mensagens de commit e informe o usuário. Use esta heurística:

• Arquivos diferentes com propósitos não relacionados → provavelmente commits separados
• Mesmo arquivo, mas preocupações distintas (por exemplo, correção de bug + refatoração) → sugira dividir
• Tudo estritamente acoplado → um commit está bom

Casos de Borda

Referência Rápida

# Obtenha seu diff preparado para colar no Copilot

…