Planos de redação

Visão geral

Elabore planos de implementação abrangentes, partindo do princípio de que o engenheiro não tem nenhum conhecimento prévio sobre nossa base de código e possui um gosto questionável. Documente tudo o que ele precisa saber: quais arquivos devem ser alterados para cada tarefa, código, testes, documentação que ele possa precisar consultar e como testar o código. Apresente o plano completo em tarefas pequenas e fáceis de assimilar. DRY. YAGNI. TDD. Commits frequentes.

Presuma que ele seja um desenvolvedor habilidoso, mas que não saiba quase nada sobre nosso conjunto de ferramentas ou domínio do problema. Presuma que ele não tenha muito conhecimento sobre um bom projeto de testes.

Anuncie logo no início: “Estou usando a habilidade ‘ writing-plans ’ para criar o plano de implementação.”

Contexto: Se estiver trabalhando em uma árvore de trabalho isolada, ela deve ter sido criada por meio da habilidade “superpowers:using-git-worktrees” no momento da execução.

Salve os planos em: docs/superpowers/plans/AAAA-MM-DD-.md

• (As preferências do usuário quanto ao local do plano substituem esse padrão)

Verificação do escopo

Se a especificação abranger vários subsistemas independentes, ela deveria ter sido dividida em especificações de subprojetos durante o brainstorming. Caso contrário, sugira dividi-la em planos separados — um por subsistema. Cada plano deve produzir, por si só, um software funcional e testável.

Estrutura de arquivos

Antes de definir tarefas, mapeie quais arquivos serão criados ou modificados e qual é a função de cada um. É aqui que as decisões de decomposição são definidas.

• Projete unidades com limites claros e interfaces bem definidas. Cada arquivo deve ter uma responsabilidade clara.
• Você raciocina melhor sobre o código que consegue manter no contexto de uma só vez, e suas edições ficam mais confiáveis quando os arquivos são focados. Prefira arquivos menores e focados em vez de arquivos grandes que fazem coisas demais.
• Arquivos que mudam juntos devem ficar juntos. Divida por responsabilidade, não por camada técnica.
• Em bases de código existentes, siga os padrões estabelecidos. Se a base de código usa arquivos grandes, não reestruture unilateralmente — mas se um arquivo que você está modificando ficou difícil de manejar, incluir uma divisão no plano é razoável.

Essa estrutura orienta a decomposição das tarefas. Cada tarefa deve produzir alterações autônomas que façam sentido independentemente.

Dimensionamento adequado das tarefas

Uma tarefa é a menor unidade que possui seu próprio ciclo de testes e merece uma avaliação por um revisor novo. Ao definir os limites das tarefas: incorpore as etapas de preparação, configuração, estrutura e documentação à tarefa cujo resultado final as necessite; divida apenas quando um revisor puder, de forma significativa, rejeitar uma tarefa enquanto aprova a vizinha. Cada tarefa termina com um resultado final testável de forma independente.

Granularidade de tarefas em pequenas partes

Cada etapa é uma ação (2 a 5 minutos):

• “Escreva o teste que falha” — etapa
• “Execute-o para garantir que falhe” – etapa
• “Implemente o código mínimo para que o teste seja aprovado” – etapa
• “Execute os testes e certifique-se de que sejam aprovados” – etapa
• “Fazer commit” — etapa

Cabeçalho do documento do plano

Todo plano DEVE começar com este cabeçalho:

# [Nome do Recurso] Plano de Implementação

> **Para colaboradores autônomos:** SUB-HABILIDADE OBRIGATÓRIA: Use superpowers:subagent-driven-development (recomendado) ou superpowers:executing-plans para implementar este plano tarefa por tarefa. As etapas utilizam a sintaxe de caixa de seleção (`- [ ]`) para acompanhamento.

**Objetivo:** [Uma frase descrevendo o que isso desenvolve]

**Arquitetura:** [2 a 3 frases sobre a abordagem]

**Pilha de tecnologias:** [Tecnologias/bibliotecas principais]

## Restrições globais

[Os requisitos da especificação para todo o projeto — versões mínimas, limites de dependências,
regras de nomenclatura e de texto, requisitos de plataforma — uma linha para cada um, com valores exatos
copiados literalmente da especificação. Os requisitos de cada tarefa incluem implicitamente
esta seção.]

---

Estrutura da tarefa

### Tarefa N: [Nome do componente]

**Arquivos:**
- Criar: `caminho/exato/para/arquivo.py`
- Modificar: `caminho/exato/para/existing.py:123-145`
- Testar: `tests/caminho/exato/para/test.py`

**Interfaces:**
- Consome: [o que esta tarefa utiliza das tarefas anteriores — assinaturas exatas]
- Produz: [o que as tarefas posteriores dependem — nomes exatos de funções, tipos de parâmetros
  e de retorno. O implementador de uma tarefa vê apenas sua própria tarefa; este
  bloco é como ele descobre os nomes e tipos que as tarefas vizinhas utilizam.]

- [ ] **Passo 1: Escreva o teste que falha**

```python
def test_specific_behavior():
    result = function(input)
    assert result == expected
```

- [ ] **Passo 2: Execute o teste para verificar se ele falha**

Executar: `pytest tests/path/test.py::test_name -v`
Esperado: FALHA com “função não definida”

- [ ] **Passo 3: Escreva uma implementação mínima**

```python
def function(input):
    return expected
```

- [ ] **Passo 4: Execute o teste para verificar se ele é aprovado**

Execute: `pytest tests/path/test.py::test_name -v`
Esperado: APROVADO

- [ ] **Etapa 5: Fazer commit**

```bash
git add tests/path/test.py src/path/file.py
git commit -m "feat: adicionar recurso específico"
```

Sem espaços reservados

Cada etapa deve conter o conteúdo real de que um engenheiro precisa. Essas são falhas de planejamento — nunca as escreva:

• "A definir", "A fazer", "implementar mais tarde", "preencher detalhes"
• "Adicionar tratamento de erros apropriado" / "adicionar validação" / "tratar casos extremos"
• “Escrever testes para o acima” (sem código de teste real)
• “Semelhante à Tarefa N” (repetir o código — o engenheiro pode estar lendo as tarefas fora de ordem)
• Etapas que descrevem o que fazer sem mostrar como (são necessários blocos de código para as etapas de código)
• Referências a tipos, funções ou métodos não definidos em nenhuma tarefa

Lembre-se

• Sempre indique os caminhos exatos dos arquivos
• Código completo em cada etapa — se uma etapa alterar o código, mostre o código
• Comandos exatos com a saída esperada
• DRY, YAGNI, TDD, commits frequentes

Autoavaliação

Depois de escrever o plano completo, analise a especificação com um novo olhar e verifique se o plano está de acordo com ela. Essa é uma lista de verificação que você mesmo deve realizar — não uma tarefa delegada a um subagente.

1. Cobertura da especificação: dê uma olhada rápida em cada seção/requisito da especificação. Você consegue apontar uma tarefa que o implemente? Liste quaisquer lacunas.

2. Verificação de placeholders: procure em seu plano por sinais de alerta — qualquer um dos padrões da seção “Sem placeholders” acima. Corrija-os.

3. Consistência de tipos: os tipos, assinaturas de métodos e nomes de propriedades que você usou nas tarefas posteriores correspondem ao que você definiu nas tarefas anteriores? Uma função chamada clearLayers() na Tarefa 3, mas clearFullLayers() na Tarefa 7, é um bug.

Se você encontrar problemas, corrija-os diretamente no código. Não é preciso revisar novamente — basta corrigir e seguir em frente. Se você encontrar um requisito da especificação sem uma tarefa correspondente, adicione a tarefa.

Transferência de execução

Após salvar o plano, ofereça a opção de execução:

“Plano concluído e salvo em docs/superpowers/plans/.md. Duas opções de execução:

1. Orientada por subagentes (recomendado) — eu envio um novo subagente por tarefa, faço revisão entre as tarefas, iteração rápida

2. Execução em linha — execute as tarefas nesta sessão usando executing-plans, execução em lote com pontos de verificação

Qual abordagem?”

Se a opção “Orientada por subagentes” for escolhida:

• SUB-HABILIDADE OBRIGATÓRIA: Usar superpowers:subagent-driven-development
• Um subagente novo por tarefa + revisão em duas etapas

Se a opção “Execução em linha” for escolhida:

• SUB-HABILIDADE OBRIGATÓRIA: Usar superpoderes:execução-de-planos
• Execução em lote com pontos de verificação para revisão