writing-plans

Visão geral da skill writing-plans

O que a skill writing-plans faz

A skill writing-plans ajuda você a transformar uma feature spec ou um documento de requisitos em um plano de implementação detalhado antes de começar a programar. A função principal dela não é gerar ideias; é produzir um plano executável e revisável, assumindo que quem vai implementar tem pouco contexto da codebase e ainda assim precisa de orientação clara no nível de arquivos, passos de teste e sequência de tarefas.

Para quem a writing-plans é indicada

Esta skill é mais indicada para engenheiros, tech leads e fluxos com agentes que já têm um requisito bem delimitado e agora precisam de um plano de execução para Requirements Planning. Ela é especialmente útil quando o trabalho abrange vários arquivos, mexe em testes e documentação, ou será repassado para alguém diferente de quem escreveu a spec original.

O trabalho real que ela resolve

Quem usa writing-plans normalmente quer reduzir a adivinhação na implementação. O valor não é apenas “fazer um plano”, mas “fazer um plano que um engenheiro competente consiga seguir sem depender de suposições ocultas”. Isso inclui quais arquivos tocar, como quebrar o trabalho em tarefas menores, o que testar e onde o escopo deve ser dividido antes do início da implementação.

O que diferencia esta skill de um prompt genérico

A writing-plans skill tem opiniões claras nos pontos que realmente importam:

• força uma checagem de escopo antes de decompor o trabalho
• exige mapear as responsabilidades dos arquivos antes de escrever as tarefas
• prioriza incrementos pequenos e testáveis em vez de fases amplas
• assume pouco contexto de domínio por parte de quem vai implementar
• inclui um prompt de revisão para verificar se o plano é de fato implementável

Isso a torna mais forte do que um prompt de uma linha como “escreva um plano de implementação” quando a qualidade do handoff importa.

Quando a writing-plans é uma ótima escolha

Use writing-plans quando você tiver:

• uma spec, ticket ou documento de requisitos por escrito
• uma mudança em várias etapas com detalhes relevantes de implementação
• necessidade de coordenar código, testes e documentação
• um repositório em que os limites entre arquivos e a ordem de execução importam

Se você só precisa de um esboço rápido ou de uma estimativa aproximada, talvez ela seja mais pesada do que o necessário.

Como usar a skill writing-plans

Contexto de instalação da writing-plans

O repositório não expõe um instalador dedicado no nível da própria skill, então o caminho prático de writing-plans install é adicionar a coleção principal de skills e invocar esta skill a partir dela:

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

Se o seu ambiente usa outro carregador de skills, instale a coleção obra/superpowers e selecione writing-plans em skills/writing-plans.

Leia estes arquivos primeiro

Para uma avaliação rápida, comece por:

• skills/writing-plans/SKILL.md
• skills/writing-plans/plan-document-reviewer-prompt.md

O SKILL.md traz o fluxo real de planejamento. Já o prompt de revisão mostra o nível de qualidade que o plano precisa atingir, o que é útil antes de você decidir usar a skill em produção.

Quais entradas a skill precisa

O writing-plans usage funciona melhor quando você fornece:

• a spec ou os requisitos de origem
• o repositório alvo ou a área da codebase
• quaisquer restrições de arquitetura, tooling, prazo ou compatibilidade retroativa
• o local desejado para salvar o plano, caso você não queira o padrão
• se o trabalho deve ser dividido em vários planos independentes

Sem uma spec real, a skill tende a produzir uma estrutura plausível, mas com orientação de implementação mais fraca.

Comece com o anúncio obrigatório

As instruções upstream pedem explicitamente que o agente anuncie:

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

Se você estiver integrando isso a um fluxo com agentes, mantenha essa linha. Ela deixa a invocação visível e reduz ambiguidades sobre qual padrão de planejamento está sendo aplicado.

Use antes de programar, de preferência em um worktree dedicado

A skill foi pensada para planejamento pré-implementação e espera rodar em um worktree dedicado, criado upstream por um fluxo de brainstorming. Mesmo que você não use exatamente essa configuração complementar, a intenção continua válida: planeje em um contexto isolado antes de editar código, para que o plano seja um artefato deliberado e não um subproduto da programação.

Como transformar um objetivo vago em um prompt forte

Prompt fraco:

• “Make a plan for adding billing.”

Prompt mais forte:

• “Use the writing-plans skill to create an implementation plan for adding team billing to our SaaS app. Spec: docs/specs/team-billing.md. Repo areas likely involved: apps/web, services/billing, db/schema. Constraints: Stripe is already used for individual billing, do not break existing subscriptions, include migration and rollback considerations, and call out tests and docs. If the spec spans independent subsystems, propose separate plans.”

Por que isso funciona:

• nomeia a spec
• aponta arquivos ou módulos prováveis
• declara restrições que afetam a decomposição
• abre espaço para dividir o escopo, em vez de forçar um plano único e grande demais

Siga a sequência de planejamento da skill writing-plans

Um bom writing-plans guide deve seguir a ordem implícita no repositório:

1. verificar se a spec deve ser dividida em planos separados
2. mapear arquivos para responsabilidades antes de quebrar em tarefas
3. escrever tarefas pequenas e implementáveis
4. incluir testes, documentação e passos de validação
5. revisar o plano final em relação à spec

Pular a etapa de estrutura de arquivos é a forma mais comum de acabar com tarefas vagas.

O que uma boa saída da writing-plans deve incluir

Um plano forte gerado por writing-plans for Requirements Planning normalmente deve conter:

• o objetivo do plano e a spec vinculada
• os arquivos a criar ou modificar
• por que cada arquivo existe ou será alterado
• tarefas pequenas o suficiente para serem concluídas e verificadas de forma independente
• orientação de testes, e não apenas passos de codificação
• atualizações de documentação ou migração, quando fizer sentido
• detalhe suficiente para que outro engenheiro não fique travado

Se a saída for composta principalmente por fases temáticas como “backend”, “frontend” e “QA”, provavelmente está genérica demais.

Local padrão do plano e quando sobrescrever

A skill sugere salvar os planos em:

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

Sobrescreva isso quando seu repositório já tiver uma convenção de planejamento, como docs/plans/ ou specs/implementation/. O mais importante é manter consistência e usar um caminho que revisores consigam encontrar depois.

Como usar o prompt de revisão

Depois de rascunhar o plano, use plan-document-reviewer-prompt.md como modelo de revisão em uma segunda passada. Os critérios de revisão são práticos:

• completude
• aderência à spec
• decomposição das tarefas
• viabilidade de implementação

Esse é um diferencial útil da writing-plans skill: ela não para na geração do plano, mas oferece uma checagem leve de aceitação para o artefato produzido.

Fluxo prático que costuma funcionar bem

Um fluxo confiável se parece com isto:

1. reunir a spec e o contexto do repositório
2. executar writing-plans
3. verificar se a divisão do plano está correta
4. revisar os limites entre arquivos e a granularidade das tarefas
5. rodar o prompt revisor do plano
6. revisar o plano antes de começar a implementação

Assim, a skill entrega mais valor como uma etapa de controle de planejamento, e não apenas como conveniência de escrita.

FAQ da skill writing-plans

A writing-plans é boa para iniciantes?

Sim, desde que o iniciante já tenha uma spec razoavelmente concreta. A skill compensa a falta de contexto da codebase ao forçar orientação explícita sobre arquivos e testes. Ela ajuda menos quando o problema real ainda está na ambiguidade de produto.

Em que isso difere de pedir a uma IA um plano de implementação?

Prompts genéricos costumam produzir planos bem escritos, mas superficiais. A writing-plans é mais útil porque força decomposição no nível de arquivos, testabilidade e qualidade de handoff para quem vai implementar. Na prática, isso costuma reduzir retrabalho quando a programação começa.

Quando eu não devo usar a writing-plans?

Pule a skill quando:

• a mudança for pequena e localizada
• você ainda estiver decidindo o escopo do produto
• você precisar mais de exploração arquitetural do que de planejamento de execução
• o trabalho for intencionalmente experimental e provavelmente mudar de imediato

Nesses casos, anotações leves podem ser melhores do que um plano formal.

Ela exige uma stack ou framework específico?

Não. A skill é orientada a processo, não a um framework específico. O conselho dela é portátil entre stacks porque o foco está em decomposição, responsabilidade dos arquivos, testes e revisabilidade.

A writing-plans lida bem com specs grandes?

Sim, mas só se você respeitar a etapa de checagem de escopo. A fonte avisa explicitamente que vários subsistemas independentes normalmente devem virar planos separados. Se você insistir em um único plano gigante, a qualidade das tarefas tende a cair.

A writing-plans basta sozinha para Requirements Planning?

Para Requirements Planning com foco em implementação, muitas vezes sim. Para requisitos ainda em fase de descoberta, não. Ela parte do pressuposto de que você já sabe o que deve ser construído e agora precisa de um caminho confiável para construir.

Como melhorar a skill writing-plans

Dê um contexto de repositório mais forte

A forma mais fácil de melhorar os resultados de writing-plans é nomear diretórios, módulos ou arquivos prováveis. A skill quer mapear as responsabilidades dos arquivos logo no início; se você fornecer os pontos de contato mais prováveis, a saída fica mais concreta e menos genérica.

Separe subsistemas independentes desde o começo

Se a sua spec mistura preocupações não relacionadas, divida isso antes de pedir um plano final. Exemplo:

• mudanças de auth
• mudanças de billing
• mudanças na admin UI

Esses itens podem até ser lançados juntos do ponto de vista de produto, mas ainda assim merecem planos separados se puderem ser implementados e testados de forma independente.

Peça explicitamente o mapeamento de responsabilidades dos arquivos

Se o primeiro rascunho vier vago, peça:

• “List each file to add or modify and state its responsibility before writing tasks.”

Isso se alinha diretamente à estrutura da skill e costuma corrigir decomposições imprecisas.

Force uma granularidade menor nas tarefas

Um modo de falha comum são tarefas grandes demais para implementar com segurança. Peça:

• tarefas que gerem progresso testável
• limites claros por tarefa
• validação explícita após cada mudança importante

É aqui que o writing-plans usage mais melhora: tarefas menores são mais fáceis de revisar, distribuir e executar.

Torne os requisitos de teste concretos

Não peça apenas “include tests”. Em vez disso, especifique:

• qual nível de testes importa
• quais suítes de teste existentes devem ser atualizadas
• se são necessárias verificações de migração, integração ou regressão

A skill já valoriza testes, mas restrições melhores tornam o plano muito mais útil.

Melhore o primeiro rascunho com iteração guiada por revisão

Use o template de revisão como ferramenta de edição, não apenas como etapa final. Depois do primeiro plano, pergunte:

• quais requisitos estão faltando na spec
• onde as tarefas ainda não são acionáveis
• onde quem for implementar pode ficar travado
• se há aumento indevido de escopo

Isso produz uma segunda versão mais afiada do que prompts amplos como “melhore o plano”.

Fique atento a estes modos de falha comuns

A writing-plans skill fica mais fraca quando:

• a spec está incompleta
• os limites entre arquivos são chutados, e não baseados no repositório
• as tarefas descrevem resultados sem passos de implementação
• testes são mencionados, mas não conectados às mudanças no código
• um plano grande demais esconde vários entregáveis independentes

Se você identificar esses sinais, revise as entradas antes de culpar a skill.

Adicione restrições que mudam as escolhas de implementação

Restrições úteis incluem:

• requisitos de compatibilidade retroativa
• expectativas de desempenho
• segurança de migração
• ordem de deploy
• obrigações de documentação
• regras de não adicionar novas dependências

Esses detalhes ajudam writing-plans for Requirements Planning a gerar um plano adequado ao seu ambiente, em vez de um ideal genérico.

Compare o plano com as necessidades reais de handoff

O teste de qualidade correto é simples: outro engenheiro, com pouco contexto, conseguiria implementar a partir deste documento sem pedir esclarecimentos o tempo todo? Se não, melhore o plano até que escolhas de arquivos, limites das tarefas e passos de validação estejam explícitos.

Mantenha o plano enxuto e focado na implementação

A orientação de origem enfatiza DRY, YAGNI, TDD e commits frequentes. Na prática, isso significa remover tarefas duplicadas, evitar trabalho especulativo e preferir incrementos que possam ser codificados e verificados rapidamente. Esses princípios influenciam mais a qualidade da saída do que simplesmente adicionar mais texto.