writing-plans

Visão geral

O que a skill writing-plans faz

A skill writing-plans ajuda você a transformar uma especificação de produto ou um documento de requisitos técnicos em um plano completo, pronto para implementação antes de qualquer pessoa mexer no código. Ela foi projetada para cenários em que você precisa entregar uma feature ou mudança em várias etapas e quer um plano claro, decomposto, que outra pessoa engenheira consiga seguir sem contexto prévio.

Usando writing-plans, você gera um plano que:

• Assume que quem vai implementar é uma pessoa desenvolvedora experiente, mas nova no seu codebase e domínio.
• Deixa explícito quais arquivos criar ou modificar em cada parte do trabalho.
• Destaca os testes, atualizações de documentação e checagens manuais necessários.
• Quebra o trabalho em tarefas pequenas, entregáveis, com limites bem definidos.

Isso facilita repassar trabalho, revisar o plano e evitar aumento de escopo ou casos extremos escondidos. O fluxo reflete práticas como DRY, YAGNI, TDD e commits frequentes, mas o foco está em planejamento de projeto e decomposição de tarefas, não em geração de código.

Para quem é a writing-plans?

Use a skill writing-plans se você é:

• Tech lead ou gerente de engenharia que precisa de um processo de planejamento repetível para features e refactors.
• Desenvolvedor(a) individual que quer clarear a estratégia antes de implementar mudanças arriscadas ou transversais.
• Times que usam subagents ou trabalho distribuído e precisam de planos escritos claros para coordenar contribuições.

Ela é especialmente adequada quando:

• Você tem uma spec ou requisitos para uma feature, migração ou integração.
• O trabalho envolve múltiplos arquivos, componentes ou serviços.
• Você quer que outra pessoa consiga implementar o trabalho sem precisar te fazer perguntas o tempo todo.

Ela não é uma boa opção quando:

• Você ainda está brainstormando o problema ou a solução (use antes uma skill de ideação/brainstorming).
• A tarefa é minúscula (por exemplo, um ajuste de uma linha) e não requer um plano formal.
• Você busca principalmente code review ou geração de código, e não planejamento.

Como ela se encaixa no seu fluxo de trabalho

O repositório espera que writing-plans seja usada depois de uma fase de brainstorming e em um worktree dedicado para o projeto. O fluxo típico é:

1. Fazer brainstorming e refinar a spec (fora desta skill).
2. Criar ou abrir um worktree dedicado para a feature.
3. Rodar a skill writing-plans para produzir o plano de implementação.
4. Salvar o plano (por padrão) em:
   • docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md
   • ou em um local de planos de sua preferência.
5. Opcionalmente despachar um plan document reviewer subagent usando o template fornecido, para validar o plano antes da implementação.

Como usar

Instalação e configuração

1. Instale a skill writing-plans

Você pode instalar a skill diretamente do repositório obra/superpowers:

npx skills add https://github.com/obra/superpowers --skill writing-plans

Isso baixa a definição da skill writing-plans e seus prompts de apoio, para que você possa usá-la em seus próprios projetos.

2. Inspecione os arquivos principais

Após a instalação, revise estes arquivos-chave para entender e adaptar o fluxo de trabalho:

• skills/writing-plans/SKILL.md – Descrição principal de como a skill deve se comportar, incluindo escopo, estrutura do plano e suposições sobre a pessoa engenheira.
• skills/writing-plans/plan-document-reviewer-prompt.md – Template de prompt reutilizável para um subagent que revisa o plano finalizado.

Seus caminhos locais podem variar dependendo de onde você faz vendor ou mirror do repositório, mas os nomes de arquivo permanecem os mesmos.

Preparando-se para rodar writing-plans

3. Confirme sua spec e o escopo

Antes de usar writing-plans, garanta que você tem:

• Uma spec clara ou documento de requisitos para a feature ou mudança.
• Detalhes suficientes para identificar os principais componentes, integrações e restrições.

A skill inclui uma etapa de Scope Check: se sua spec cobre múltiplos subsistemas independentes, espera-se que esse trabalho tenha sido dividido em specs de subprojetos separados durante o brainstorming. Se isso não aconteceu, você deve:

• Quebrar o trabalho em planos separados, um por subsistema.
• Garantir que cada plano gere um software funcional e testável por conta própria.

Isso evita que um único plano se torne imanejável e ajuda a alinhar o trabalho com unidades implantáveis.

4. Prepare um worktree e o arquivo de plano

As orientações upstream assumem que você:

• Trabalha em um worktree dedicado para a feature (configurado durante o brainstorming).

• Salva o plano de implementação resultante em:

  • docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md

Você pode sobrescrever esse local se o seu time preferir outra estrutura de diretórios, como docs/plans/ ou planning/. O importante é que o plano seja commitado no version control, versionado junto com o código e fácil de encontrar depois.

Rodando a skill e escrevendo um plano

5. Anuncie e inicie a sessão de planejamento

Ao invocar a skill ou iniciar a conversa de planejamento, a orientação é declarar explicitamente:

"I'm using the writing-plans skill to create the implementation plan."

Isso deixa claro que o objetivo é um plano de implementação estruturado, não exploração de design ou saída de código.

6. Mapeie primeiro a estrutura de arquivos

Antes de listar tarefas, writing-plans enfatiza a decomposição em nível de arquivos:

• Identifique quais arquivos serão criados ou modificados.
• Atribua a cada arquivo uma responsabilidade única e clara.
• Projete unidades com interfaces e limites bem definidos.

Nesse estágio, o plano deve responder:

• Onde a nova lógica vai viver?
• Quais arquivos existentes serão alterados, e por quê?
• Como esses arquivos interagem em alto nível?

Definir cedo uma estrutura de arquivos sensata torna a decomposição de tarefas, as revisões e futuros refactors muito mais fáceis.

7. Quebre o trabalho em tarefas pequenas

Com o mapa de arquivos definido, use writing-plans para transformar a spec em uma sequência de tarefas pequenas, independentes e compreensíveis. As orientações upstream destacam:

• Cada tarefa deve ter um objetivo claro e ser acionável.
• As tarefas devem ser pequenas o suficiente para permitir commits frequentes.
• O plano deve ser DRY (sem instruções redundantes) e evitar trabalho YAGNI (sem tarefas especulativas).

Para cada tarefa, o plano deve incluir:

• Quais arquivos serão tocados.
• Que código ou configuração precisa mudar em alto nível.
• Quais testes devem ser adicionados ou atualizados.
• Quais documentos precisam ser atualizados.

A meta é que uma pessoa engenheira com contexto mínimo consiga pegar qualquer tarefa isolada e concluí-la com segurança.

8. Planeje testes e documentação

writing-plans espera que você incorpore testes e documentação diretamente no plano:

• Identifique unit tests, testes de integração ou end-to-end que precisam ser adicionados ou atualizados.
• Indique como rodar os testes (por exemplo, comandos, entry points) quando relevante.
• Especifique as atualizações de documentação necessárias, como seções de README, guias de usuário ou API docs.

Isso garante que qualidade e manutenibilidade sejam partes centrais do plano, não algo deixado para depois.

Revisando e iterando no plano

9. Use o template de plan document reviewer (opcional, mas recomendado)

O arquivo plan-document-reviewer-prompt.md fornece um prompt estruturado para um plan document reviewer subagent. O objetivo é:

• Verificar se o plano está completo e condiz com a spec.
• Validar se a decomposição de tarefas é realista e acionável.
• Confirmar se uma pessoa engenheira conseguiria implementar o plano sem travar.

O template lista categorias para o revisor checar, incluindo:

• Completeness – Sem TODOs, placeholders ou passos faltando para requisitos importantes.
• Spec Alignment – O plano cobre a spec sem grande aumento de escopo.
• Task Decomposition – As tarefas têm limites claros e são implementáveis.
• Buildability – Uma pessoa desenvolvedora competente consegue seguir o plano de ponta a ponta.

O revisor é instruído a focar em pontos que possam causar problemas reais na implementação, não em detalhes de redação ou estilo.

Você pode integrar essa etapa de revisão ao seu CI, fluxos de code review ou processo de revisão manual.

10. Itere com base no feedback

Se o revisor (humano ou subagent) encontrar problemas como requisitos faltando, passos contraditórios ou tarefas vagas demais:

• Atualize o arquivo de plano com as correções.
• Rode ou dispare o revisor novamente, se necessário.
• Depois que o plano for aprovado, trate-o como a fonte de verdade para a implementação.

Adaptando writing-plans ao seu time

11. Personalize a estrutura e as convenções

Embora a skill upstream defina comportamentos e padrões claros, você pode adaptá-la:

• Mudando o local do arquivo de plano para combinar com o layout do seu repositório.
• Adicionando checklists específicos do time (por exemplo, revisão de segurança, testes de performance) como tarefas recorrentes.
• Integrando o plano ao seu issue tracker, mapeando tarefas para tickets.

Como writing-plans é principalmente sobre fluxo de trabalho estruturado e gestão de projeto, ela se adapta bem a diferentes linguagens, frameworks e domínios.

FAQ

Quando devo usar a skill writing-plans?

Use writing-plans sempre que você tiver uma feature, refactor ou integração em múltiplas etapas e uma spec razoavelmente clara, e quiser um plano de implementação escrito que outra pessoa engenheira consiga executar sem contexto. Ela é especialmente útil antes de mudanças complexas que tocam múltiplos arquivos ou subsistemas.

Quando writing-plans não é uma boa escolha?

writing-plans não é ideal quando:

• Você ainda está explorando soluções e a spec é instável.
• O trabalho é pequeno a ponto de um plano formal ser apenas overhead.
• Você está buscando apenas geração de código ou code review, e não decomposição de tarefas e planejamento de projeto.

Nesses casos, use skills focadas em brainstorming, design ou codificação.

Eu preciso usar obrigatoriamente o caminho padrão docs/superpowers/plans/?

Não. A orientação upstream sugere salvar os planos em:

• docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md

Mas também deixa claro que as preferências do usuário quanto ao local do plano substituem esse padrão. Você pode manter os planos em qualquer diretório ou esquema de nomes que se encaixe nos padrões do seu repositório e documentação.

Posso usar writing-plans para projetos que não envolvem código?

A skill foi escrita pensando em projetos de software e codebases, incluindo mapeamento de arquivos e testes. Porém, as ideias centrais — quebrar o trabalho em tarefas menores, mapear responsabilidades e checar completude — podem ser adaptadas a outros fluxos de trabalho técnicos. Ela será mais eficaz onde exista ao menos alguma noção de arquivos, testes ou documentação a atualizar.

Como writing-plans ajuda com onboarding e handoffs?

Como writing-plans parte da premissa de que quem implementa tem zero contexto do seu codebase e gosto duvidoso, ela incentiva você a:

• Explicar onde o código deve ficar e por quê.
• Tornar testes e docs explícitos.
• Remover ambiguidade das tarefas.

Isso torna muito mais fácil repassar trabalho para novas pessoas do time, contratados ou subagents. Eles podem seguir o plano diretamente, em vez de tentar deduzir a intenção apenas pela spec.

Como writing-plans se relaciona com ferramentas de gestão de projetos?

writing-plans complementa, em vez de substituir, ferramentas de gestão de projetos:

• Ela fornece um plano escrito e estruturado que explica como implementar a spec em nível de código e arquivos.
• A partir daí, você pode mapear as tarefas do plano em ferramentas como Jira, GitHub Issues ou Linear.

A skill fica na interseção entre gestão de projetos, templates de workflow e escrita técnica, oferecendo um padrão reutilizável para planos de implementação consistentes.

Posso usar apenas o reviewer prompt sem a skill completa?

Sim. O arquivo plan-document-reviewer-prompt.md pode ser usado de forma independente como um template de review para qualquer documento do tipo plano. Você pode despachá-lo como prompt de um subagent para:

• Revisar planos escritos com writing-plans.
• Checar planos criados por outros processos ou ferramentas.

No entanto, você terá resultados mais consistentes quando tanto o plano quanto a revisão seguirem o fluxo de trabalho do writing-plans.