Carlososuna11/claude-skills

Disciplina de PR

Visão Geral

PRs custam tempo da equipe. A disciplina aqui é prevenir o desperdício (re-revisão por escopo surpreendente, merge na branch errada, atribuição incorreta) antes de produzi-lo.

Princípio: consenso prévio quando envolve arquitetura, formato consistente sempre, merge target verificado duas vezes.

Anunciar no início: "Aplicando pr-discipline para este PR."

Passo 1: Alinhar com o mantenedor ANTES de codificar (se aplicável)

Enviar um parágrafo de proposta ao mantenedor do módulo antes de abrir o PR se a alteração envolver:

• Forma de resposta de endpoints existentes.
• Estrutura de DTOs ou validators.
• Padrões cross-repo (validators, services, tratamento de erros).
• Abstrações arquitetônicas (novos decoradores, camadas de serviço, padrões a nível de módulo).

Template:

"[Mantenedor], vou fazer X para funcionalidade Y. Escopo: a, b, c. Outros X permanecem como estão por razão Z. OK?"

Aguardar acknowledgment. Se houver push-back, iterar em texto (barato). Se aprovar, o PR passa sem debate posterior.

Não se aplica a: bug fixes que não alteram contratos, funcionalidades que seguem padrões existentes, refactors internos de um módulo, docs ou tests isolados.

Passo 2: Verificar a base correta do PR

A branch base do PR nem sempre é main. Resolva-a invocando a habilidade use-worktrees (Passo 1 — waterfall completo). Uma vez resolvida, fica persistida na auto-memória e futuras invocações a usam sem perguntar.

Fluxos comuns que esta habilidade respeita:

Fluxo	Feature branch parte de	PR aponta para
Backend com staging buffer	staging	staging (depois staging → main separadamente)
Mobile / web simples	main ou main-web	main ou main-web
Gitflow tradicional	dev	dev (depois dev → master)
Trunk-based	main ou trunk	main ou trunk

Não assumir; resolver sempre.

Passo 3: Reutilizar antes de criar

Antes de adicionar qualquer arquivo, validator, guard, serviço, componente, helper, constante ou tipo novo: invocar a habilidade reuse-existing-patterns. Essa habilidade cobre como buscar (por categoria), quando usar o existente e quando é legítimo criar um paralelo (com justificativa no body do PR).

Não comece a codificar sem ter passado por esse reflexo — é o motivo número um de comentários de revisão do tipo "isso já existe, use o padrão atual".

Passo 4: Criar o PR — título, corpo, atribuição

Título

• Abaixo de 70 caracteres. O longo vai no corpo.
• Formato do repo (Conventional Commits se houver; se não, frase curta).
• No idioma da equipe (se a equipe escreve em espanhol, o título vai em espanhol).

Corpo

Template mínimo:

## Resumo
<1-3 bullets do QUE muda e POR QUÊ>

## Plano de teste
- [ ] <comando ou fluxo a verificar>
- [ ] <outro>

## Risco
<edge cases, plano de rollback, dependências>

Se o repo tiver template (.github/PULL_REQUEST_TEMPLATE.md), usá-lo como base.

Atribuição (commit identity)

Nunca passar -c user.email=... nem -c user.name=... a git commit. O repo do trabalho tem config local correta; a global costuma ser pessoal. Sobrescrever acidentalmente atribui commits do trabalho à conta pessoal do GitHub.

Verificar antes de fazer push:

git log -1 --format='%an <%ae>'

Se o email não for o de trabalho, não fazer push — corrigir antes:

git commit --amend --reset-author   # usa a config local atual

Não reescrever história de main/staging (branches protegidas) somente por atribuição — o custo do force-push supera o benefício.

Passo 5: Subir markdown com backticks limpos

gh pr edit --body-file e gh pr comment --body escapam os backticks para \`, quebrando a formatação. Solução: gh api -X PATCH` com JSON payload.

python3 <<'PY'
import json, subprocess
with open('/tmp/body.md') as f:
    body = f.read()
subprocess.run(
    ['gh', 'api', '-X', 'PATCH', 'repos/<org>/<repo>/pulls/<num>', '--input', '-'],
    input=json.dumps({'body': body}), text=True, check=True
)
PY

Verificar:

gh pr view <num> --json body --jq .body | head -10

Se os backticks saírem literais (não escapados), está limpo.

Passo 6: Estilo de comentários de revisão

• Agrupar por severidade: Bloqueante / Melhorias menores / Nits.
• Um bullet por achado, em uma linha: o que + por que + correção sugerida.
• Formato arquivo.ts:42 para referenciar linhas (clicável no GitHub).
• Comece com a razão antes da observação. Como notas na margem de um colega, não como auditoria externa.
• Se o autor documentou sua linha de raciocínio no body do PR, envolva-se com essa linha de raciocínio — não a reinvente desde primeiros princípios.
• Sem tags artificiais tipo "B1", "M2". Sem code blocks de exemplo quando não agregam.

O que um revisor humano experiente nota como "AI dump": estrutura muito simétrica, mesmas frases de transição, bullets sem contexto do autor.

Passo 7: Merge — squash vs merge conforme o fluxo da equipe

Verificar a convenção do repo. Padrões comuns:

Tipo de repo	feature → integration	integration → main
Backend com staging	squash	merge commit
Mobile/web sem staging	squash ou merge	N/A
Gitflow tradicional	merge em dev	merge em master

Por que a assimetria em repos com staging: se você fizer squash de staging → main, o PR parece gigante (repete N features já squasheadas). O merge commit preserva a lista de features tal qual caíram em staging.

# feature → staging
gh pr merge --squash <num>

# staging → main (em repos que separam)
gh pr merge --merge <num>

NUNCA fazer merge direto em main se o repo tiver staging:

• git revert desfaz o código mas os commits ficam na história para sempre — visíveis para toda a equipe.
• Triplo verificar o --base de gh pr create e o target do merge na UI do GitHub antes de pressionar.
• Perguntar ao usuário "faço merge no staging?" antes de executar gh pr merge se houver dúvida.

Referência Rápida

Situação	Ação
Alteração envolve contratos ou arquitetura	Passo 1: alinhar com mantenedor
Criar branch	Passo 2: resolver base com waterfall
Iniciar implementação	Passo 3: buscar se o padrão já existe no repo
Pronto para abrir PR	Passo 4: título <70, corpo com template, verificar atribuição
Body ou comment com código	Passo 5: gh api PATCH com JSON
Deixar revisão	Passo 6: bullets por severidade, comece com razão
Merge	Passo 7: squash vs merge conforme convenção
Repo com staging	NUNCA fazer merge direto em main

Erros Comuns

• Abrir PR arquitetônico sem pré-alinhamento. Produz 2-3 rodadas de re-revisão e debate posterior. Enviar o parágrafo de proposta antes de codificar.
• Criar arquivo ou abstração nova quando já existe equivalente. Buscar primeiro (Passo 3). O revisor vai apontar.
• Título > 70 chars com a descrição completa. Título curto, o detalhe vai no corpo.
• Passar -c user.email para commits scriptados. Sobrescreve a config local de trabalho com a global pessoal.
• gh pr edit --body-file file.md com backticks. Escapa-os. Usar gh api PATCH com JSON.
• Revisões em prosa narrativa. O usuário quer bullets por severidade — escaneável, não narrativa.
• Squash de staging → main. Repete história que já foi squasheada em cada feature. Usar merge commit.
• Merge direto em main "porque é pequeno". Os commits ficam na história para sempre, visíveis para todos.

Bandeiras Vermelhas

Nunca:

• Abrir PR que envolve contratos/arquitetura sem alinhamento prévio.
• Criar arquivo ou abstração paralela quando já existe equivalente.
• Passar -c user.email / -c user.name para git commit.
• Fazer push sem verificar git log -1 --format='%ae'.
• Usar gh pr edit --body-file para markdown com backticks.
• Merge direto em main em repo com staging.
• Squash de staging → main.
• Deixar revisão sem agrupar por severidade.

Sempre:

• Pré-alinhar mudanças arquitetônicas com o mantenedor.
• Resolver a base do PR com o waterfall, não assumir main.
• Buscar se o padrão já existe no repo antes de criar um novo.
• Título <70 + corpo com Resumo + Plano de teste + Risco.
• Verificar atribuição do commit antes do push.
• gh api PATCH com JSON para markdown com código.
• Bullets por severidade em revisões, comece com razão.
• Squash em feature → integration, merge commit em integration → main.