finishing-a-development-branch

Visão geral

O que esta skill faz

A skill finishing-a-development-branch ajuda você a finalizar com segurança uma branch de desenvolvimento Git assim que o trabalho estiver implementado e a suíte de testes estiver passando. Ela conduz você por um fluxo de trabalho claro e repetível para decidir se deve fazer merge localmente, dar push e abrir um Pull Request, deixar a branch para depois ou descartá-la completamente.

O princípio central da skill é simples:

Verificar testes → Determinar a base branch → Apresentar opções → Executar a escolha → Fazer a limpeza

Em vez de comandos Git ad hoc ou de esquecer verificações importantes, finishing-a-development-branch oferece ao seu agente um checklist consistente para o fechamento de uma feature branch ou bugfix branch.

Para quem é a finishing-a-development-branch?

• Desenvolvedores que trabalham com branches Git e querem um ritual estruturado de “fim de branch”
• Times que exigem testes passando antes de fazer merge ou abrir um PR
• Usuários do conjunto de skills obra/superpowers que querem que agentes gerenciem fluxos Git com mais segurança
• Qualquer pessoa que se pergunta regularmente: “Esta branch está pronta para merge? E como devo integrar?”

Ela se encaixa especialmente bem em repositórios que já têm testes automatizados e branches base padrão, como main ou master.

Problemas que esta skill resolve

• Esquecer de rodar testes antes de fazer merge ou abrir um Pull Request
• Ficar em dúvida sobre de qual branch uma feature branch foi criada
• Tomar decisões inconsistentes entre fazer merge local, usar PRs ou descartar o trabalho
• Branches esquecidas que poluem o repositório porque o passo de finalização nunca ficou claro

Ao impor uma checagem de testes primeiro e depois apresentar um conjunto pequeno de opções explícitas, finishing-a-development-branch reduz erros e torna seu fluxo Git mais previsível.

Quando esta skill é uma boa escolha

Use finishing-a-development-branch quando:

• Uma feature ou correção estiver totalmente implementada
• Você espera que todos os testes passem ou quer bloquear a integração se houver testes falhando
• Você estiver pronto para decidir como esta branch deve ser integrada ou se deve ser descartada

Ela não é uma boa escolha quando:

• Você ainda está codando ativamente ou experimentando na branch
• O repositório não tem testes utilizáveis e você não consegue rodar uma suíte de testes significativa
• Você precisa de um gerenciamento de releases com múltiplas branches, mais complexo do que um fluxo simples feature → base branch

Se a sua necessidade principal for ajuda para escrever código ou revisar mudanças, considere combinar esta skill com outras focadas em implementação ou code review; finishing-a-development-branch é especificamente sobre o passo final de integração.

Como usar

Instalação e configuração

1. Instale a skill

Instale finishing-a-development-branch a partir do repositório obra/superpowers usando o Skills CLI:

npx skills add https://github.com/obra/superpowers --skill finishing-a-development-branch

Isso torna a skill disponível no ambiente do seu agente para que ela possa aplicar o fluxo Git guiado ao seu repositório atual.

2. Confirme os pré-requisitos do repositório

Para que a skill funcione como esperado, seu projeto deve:

• Ser um repositório Git com uma base branch clara (normalmente main ou master).
• Ter uma suíte de testes executável, normalmente via comandos como:
  • npm test
  • cargo test
  • pytest
  • go test ./...

O comando exato depende do seu stack; a skill espera que exista algum comando de teste que possa ser executado antes da integração.

3. Anuncie o uso da skill

Quando você iniciar o processo de finalização, a skill espera que você (ou seu agente) anuncie explicitamente:

"I'm using the finishing-a-development-branch skill to complete this work."

Isso mantém o fluxo transparente para colaboradores e sinaliza que o processo estruturado está em uso.

Etapas do fluxo guiado

Etapa 1: Verifique os testes

Antes de qualquer decisão de integração, a skill roda ou pede para você rodar a suíte de testes do projeto. Comandos típicos incluem:

npm test
# or
cargo test
# or
pytest
# or
go test ./...

• Se os testes falharem: a skill informa o número de falhas, mostra os erros e interrompe o processo. Ela indicará que não pode prosseguir com merge ou PR até que os testes passem.
• Se os testes passarem: o fluxo segue para a próxima etapa.

Esse bloqueio rigoroso “testes primeiro” ajuda a evitar que código quebrado seja incluído em um merge ou enviado em um Pull Request.

Etapa 2: Determine a base branch

Em seguida, finishing-a-development-branch identifica de qual branch sua branch de desenvolvimento foi criada, usando comandos Git como:

git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null

Se a branch base não puder ser determinada automaticamente, a skill recorre a uma pergunta de esclarecimento, como:

"This branch split from main - is that correct?"

Confirmar a base branch correta é importante porque isso define para onde seu trabalho será feito o merge ou qual branch o Pull Request deve mirar.

Etapa 3: Apresente as opções de integração

Quando os testes passam e a base branch é conhecida, a skill apresenta exatamente quatro opções concisas:

Implementation complete. What would you like to do?

1. Merge back to <base-branch> locally
2. Push and create a Pull Request
3. Keep the branch as-is (I'll handle it later)
4. Discard this work

Which option?

As opções são propositalmente curtas e diretas, sem muita explicação, para que você escolha rapidamente.

Casos de uso típicos:

• Opção 1 – Você quer um merge local rápido, comum em projetos pessoais menores ou quando é o único mantenedor.
• Opção 2 – Você trabalha em equipe e precisa de code review, CI ou aprovações via uma plataforma de hospedagem Git como o GitHub.
• Opção 3 – Você ainda não quer decidir, mas deseja garantir que os testes passaram e que o estado da branch está claro.
• Opção 4 – Você estava experimentando ou a abordagem ficou obsoleta e deseja remover a branch de forma limpa.

Etapa 4: Execute a opção escolhida

Com base na sua resposta, a skill executa as ações Git correspondentes e qualquer limpeza relacionada. Embora o SKILL.md original omita alguns comandos detalhados, a intenção é:

• Para merge local: fazer checkout da base branch, dar merge na branch de desenvolvimento e, se fizer sentido, deletar a branch concluída.
• Para push + PR: dar push na branch para o remoto e guiar você na criação de um Pull Request apontando para a base branch identificada.
• Para manter como está: deixar a branch atual intocada e registrar claramente que você cuidará da integração depois.
• Para descartar: descartar ou deletar a branch com segurança após confirmar que é realmente isso que você quer.

Ao longo desta etapa, a skill prioriza previsibilidade e segurança: não fazer merge com testes falhando, não fazer merge na base branch errada e evitar perda acidental de trabalho.

Dicas práticas de uso

Integre ao seu fluxo de trabalho pessoal

• Rode finishing-a-development-branch sempre que você considerar que uma feature está “pronta”.
• Use o bloqueio de testes como sua checagem final de qualidade antes de decidir entre merge e PR.
• Use a Opção 2 por padrão em ambientes de time para garantir que reviews e pipelines de CI sejam disparados.

Use conforme as convenções do time

Se o seu time tiver regras específicas de branching e review (por exemplo, sempre fazer PR para develop antes, ou nunca deletar branches automaticamente), alinhe o uso das opções com essas regras. A estrutura da skill ajuda a aplicar essas políticas de forma consistente.

Combine com outras skills superpowers

Dentro da suíte obra/superpowers, finishing-a-development-branch foi pensada para complementar skills que ajudam em implementação, refatoração ou testes. Use essas para evoluir a branch e chame esta skill quando estiver realmente pronto para integrar.

FAQ

Quando devo rodar a skill finishing-a-development-branch?

Rode finishing-a-development-branch quando suas mudanças estiverem implementadas, você esperar que os testes passem e estiver pronto para decidir como integrar a branch (merge, PR, manter ou descartar). Ela foi feita para ser o passo final no ciclo de vida da branch, não um assistente de desenvolvimento do dia a dia.

O que acontece se os testes falharem?

Se os testes falharem, a skill relata as falhas e interrompe o processo. Ela não vai prosseguir para merge nem para criação de Pull Request. Você deve corrigir os testes que falharam na branch, rodá-los novamente e só então invocar finishing-a-development-branch de novo.

Posso usar sem uma suíte de testes automatizada?

A skill foi desenhada em torno do princípio “verificar testes primeiro”. Embora seja teoricamente possível adaptá-la a um projeto sem testes, isso significaria abrir mão de uma das principais proteções. Para melhores resultados, use em repositórios onde você pode rodar comandos como npm test, cargo test, pytest ou go test ./....

Como ela decide em qual branch fazer merge?

finishing-a-development-branch tenta determinar a base branch usando o merge-base do Git contra nomes de branch comuns como main ou master. Se isso for ambíguo, ela pedirá que você confirme qual deve ser a base branch. Isso garante que merges e Pull Requests sejam direcionados para a branch correta.

Ela cria Pull Request automaticamente?

O comportamento documentado da skill é “push and create a Pull Request” quando você escolhe a Opção 2. A mecânica exata depende de como o ambiente do seu agente está configurado com sua plataforma de hospedagem Git. No mínimo, ela fará push da sua branch e vai orientar você a abrir um PR contra a base branch detectada.

Ela vai deletar minha branch automaticamente?

A descrição da SKILL enfatiza apresentar opções e executar o fluxo escolhido, incluindo a limpeza. O comportamento de deleção exato pode depender de como seu ambiente interpreta a etapa de cleanup. Trate a Opção 4 (discard this work) como potencialmente destrutiva e só a escolha quando tiver certeza de que não precisa mais da branch.

finishing-a-development-branch é adequada para fluxos de release complexos?

Esta skill é voltada para branches simples de feature ou fix que fazem merge de volta em uma única base branch. Se você gerencia múltiplas branches de release de longa duração, fluxos de hotfix ou pipelines de deploy complexos, ainda pode usar finishing-a-development-branch por branch, mas provavelmente vai precisar de processos ou ferramentas adicionais para cobrir a estratégia de release como um todo.

Como instalo finishing-a-development-branch mesmo?

Use o Skills CLI apontando para o repositório obra/superpowers:

npx skills add https://github.com/obra/superpowers --skill finishing-a-development-branch

Depois de instalar, siga o fluxo da skill: rode os testes, confirme a base branch, escolha uma opção e deixe a skill cuidar dos passos de integração e limpeza.