jeffyfung/skills

Confirmar, Enviar e Abrir um PR

Envia o trabalho no branch de funcionalidade atual: commit → push → PR. A porta de confirmação (etapa 6) protege o push — nunca pule, mesmo se invocado consecutivamente na mesma rodada.

Recebe um argumento opcional: o branch base. Sem ele, a etapa 5 resolve a base.

1. Proteger o branch

git branch --show-current. Se for main/master, pare e informe ao usuário para criar um branch de funcionalidade primeiro — nunca faça commit ou push diretamente para main.

2. Escopo do commit

git status + git diff. Prepare apenas os arquivos que pertencem à tarefa atual. Arquivos não rastreados que parecem saída de rascunho, dados gerados ou fixtures de teste locais (CSVs, *_results/*, logs) não são preparados automaticamente — liste-os e pergunte ao usuário se deseja incluí-los, ignorá-los ou adicioná-los ao .gitignore.

3. Verificações de pré-commit

Consulte os comandos de formatação/lint do repositório — verifique AGENTS.md, CLAUDE.md e README.md (nesta ordem) em busca de um formatador/linter documentado e execute o que estiver especificado lá. Não use dotnet format ou qualquer outro palpite específico de ferramenta se nenhum desses documentos nomear um — observe que nenhum formatador/linter está documentado e prossiga.

Se a alteração tocar em código testado e uma execução de teste direcionada rápida estiver disponível, execute-a; não execute a suíte completa apenas para fazer um commit.

4. Mensagem de commit

Commits Convencionais (feat|fix|test|docs|refactor(escopo): resumo), combinando com o estilo já presente em git log para este repositório. Corpo apenas quando o "porquê" não for óbvio a partir do diff.

5. Resolver o branch base

A base é main a menos que o trabalho seja empilhado — construído sobre um branch de funcionalidade que ainda não foi mesclado, onde basear em main arrastaria o branch abaixo para este diff.

1. Argumento fornecido — essa é a base. Verifique com git rev-parse --verify origin/<base>; se a referência não existir, informe e use main.
2. Sem argumento — procure um candidato. Qualquer um destes:
   • A conversa indica que este trabalho está sobre commits feitos em outro branch.
   • O trabalho vem de um ticket bloqueado por, ou dependente de, outro ticket — o branch que resolve o bloqueador é o candidato.
   • git log --oneline origin/main..HEAD mostra commits que esta tarefa não produziu; git branch -r --contains <sha> nomeia de onde eles vieram.
3. Validar o candidato. Ele deve existir no remoto, ser diferente do branch atual e estar ausente de git branch -r --merged origin/main — um candidato já mesclado em main está morto.
4. Nenhum candidato, ou falha na validação — main.

Um candidato validado é uma sugestão, não uma decisão: ofereça-o junto com main na porta da etapa 6 e deixe o usuário escolher.

6. Porta de confirmação — push

Mostre ao usuário a mensagem de commit, git diff --stat (ou o commit, uma vez feito) e a base da etapa 5 — ambas as opções quando a etapa 5 encontrou um candidato. Obtenha aprovação explícita antes de git push -u origin <branch>. Enviar publica o branch — trate como unidirecional. A criação do PR depende dessa mesma confirmação (veja etapa 7) e não precisa de aprovação separada.

7. Abrir o PR

Verifique primeiro se já existe um PR para este branch: gh pr list --head <branch> --state all.

• PR aberto encontrado — reutilize-o, não abra uma duplicata. Informe sua URL.
• PR mesclado encontrado — o branch já foi enviado uma vez; pare e pergunte ao usuário o que ele deseja antes de criar outro PR (novos commits desde a mesclagem são incomuns, não o caso padrão).
• Nenhum PR existente/mesclado — a confirmação de push da etapa 6 já cobre isso: rascunhe o corpo e execute gh pr create --base <base> --head <branch> --title "<título>" --body "<corpo>" imediatamente, sem aprovação extra.

Capturas de tela para alterações visíveis na UI. Se a alteração modificar algo que o usuário possa ver — um novo campo de texto, uma cor alterada, novo layout ou texto, uma nova página ou componente — capture capturas de tela do caminho feliz e dos casos extremos que a alteração introduz (estados vazio e de erro, texto longo/transbordando, responsivo vs desktop onde relevante). Faça upload com gh pr create --attach '<caminho>#<texto alternativo>' (repita por imagem; gh pr edit <pr> para adicionar a um PR existente). Se o corpo referenciar o mesmo caminho — por exemplo, ![Caminho feliz](./pr-shots/feliz.png) sob um título ## Capturas de tela — o gh reescreve a referência para a URL enviada no lugar; caso contrário, os anexos são adicionados ao final do corpo. Isso funciona para repositórios privados: os anexos são visíveis para qualquer pessoa com acesso ao repositório. Mantenha os arquivos fora do commit (um diretório temporário) — eles são enviados, não versionados. Requer gh ≥ 2.99; em versões mais antigas, arraste as imagens para o corpo do PR na interface web. Pule apenas quando a alteração for invisível para o usuário (lógica, testes, configuração, documentação, CI).

Antes de rascunhar, verifique se o repositório tem seu próprio padrão de descrição de PR — .github/PULL_REQUEST_TEMPLATE.md, .github/pull_request_template.md, orientação em docs/* ou CONTRIBUTING.md sobre corpos de PR. Um modelo documentado no repositório substitui o abaixo; use-o em vez disso.

Modelo de corpo de PR (fallback — o padrão do repositório prevalece se existir)

## Resumo
<o que mudou e por que, 1-6 frases>

## Alterações
- <alteração notável 1>
- <alteração notável 2>

## Capturas de tela
<para alterações visíveis na UI: caminho feliz + casos extremos relevantes; omitir para alterações invisíveis>

## Decisões de design
<compensações notáveis ou alternativas rejeitadas — apenas para grandes alterações funcionais, veja abaixo>

## Testes
<comandos executados / como verificado>

## Acompanhamentos
<trabalho adiado, ou "Nenhum">

Quando a base não for main, abra o Resumo nomeando o branch base e o que precisa ser entregue primeiro — o revisor precisa saber que o diff é empilhado e que o PR será redirecionado para main assim que a base for mesclada.

Inclua decisões de design apenas quando o PR introduzir novo comportamento funcional de tamanho real (um novo módulo, um algoritmo não trivial, uma compensação sobre a qual um revisor teria que perguntar) — omita a seção completamente para documentação/configuração/tarefas/correções pequenas, em vez de deixá-la vazia.

8. Revisão guiada (apenas alterações amplas)

Escreva um HTML independente de revisão guiada quando qualquer destas condições for verdadeira:

• o diff toca em vários módulos não-UI diferentes;
• altera um esquema de banco de dados (migrações, tabelas, colunas, índices, restrições);
• é uma funcionalidade grande de ponta a ponta (um novo fluxo cruzando várias camadas).

Pule para documentação, configuração, tarefas, correções pequenas e alterações confinadas a um módulo ou apenas à UI. A revisão guiada existe para encurtar uma revisão — não a gere automaticamente para cada PR.

Escreva um arquivo, pr-walkthrough.html, em um diretório temporário fora do commit (nunca o prepare), abra-o localmente com open pr-walkthrough.html e forneça ao usuário o caminho. Não o hospede, anexe ou versiona.

Estruture-o como seções sob cabeçalhos colapsáveis nativos <details>/<summary> — a primeira seção aberta, o restante colapsado — para que o revisor varra os cabeçalhos e expanda apenas o que precisa. Sem JavaScript.

Escrito para um revisor que não leu o diff:

• O quê e por quê — a alteração em algumas frases, mais a ordem para ler o diff.
• Mapa de alterações — quais módulos são tocados e como se conectam. Um diagrama, não uma lista de arquivos.
• Mecânica — cada peça não óbvia de lógica ou fluxo de dados explicada ao lado do código que nomeia (caminho:linha).
• Alterações de esquema — formas de tabela antes/depois, o caminho de migração e o risco (locks, backfill, rollback).
• Partes difíceis — as partes sobre as quais um revisor teria que perguntar e o que examinar.

Diagramas: SVG inline, escritos à mão e dimensionados para o conteúdo, para dependências de módulos, fluxo de solicitação/sequência e esquema. Mantenha o arquivo autocontido — sem JS, CSS ou URLs de imagem externos, para que abra offline. Use imagens renderizadas ou capturas de tela apenas onde a coisa sendo explicada é visual.

9. Relatório

Forneça ao usuário a URL do PR e a base que ele almeja. Declare claramente o que foi commitado, enviado e aberto — sem hesitações.