proponir-plano-de-implementacao

Skill: Propor Plano de Implementação

Propósito

Criar um plano de implementação em TOML que guia o skill implement-commit. O plano deve ser interpretável por máquina — o orquestrador o lê mecanicamente.

Quando Usar

• O documento de design da funcionalidade existe e foi aprovado
• Pronto para iniciar a implementação
• Necessidade de coordenar trabalho ou acompanhar o progresso

Pré-requisitos

• Design da funcionalidade existe em docs/features/NNNN-feature-name/design.md
• Plano de teste existe em docs/features/NNNN-feature-name/test-plan.md

Formato de Saída

Crie docs/features/NNNN-feature-name/implementation-plan.toml:

[meta]
feature = "nome-da-funcionalidade"
feature_dir = "docs/features/NNNN-nome-da-funcionalidade"
workspace = "./caminho/para/workspace"

[dependencies]
1 = []
2 = []
3 = [1, 2]

[[commits]]
id = 1
title = "Descrição curta"
message = "feat(escopo): mensagem de commit convencional"
files = ["caminho/para/arquivo.rs"]  # Relativo ao workspace
acceptance = ["Critério da tabela CC (CC-N)"]
anti_patterns = ["O que NÃO fazer"]
tests = ["nome_do_teste_do_plano_de_teste"]  # OBRIGATÓRIO: mapeia para test-plan.md

Procedimento

1. Estudar o Documento de Design

Leia design.md minuciosamente, anotando:

• Estrutura de módulos e arquivos afetados
• Dependências entre componentes
• Tabela de Restrições Críticas (CC-1, CC-2, etc.)

2. Estudar o Plano de Teste (CRÍTICO)

Leia test-plan.md e crie um mapeamento:

• Liste TODOS os nomes de teste da tabela de Cobertura de Requisitos
• Cada teste DEVE ser atribuído a exatamente um commit
• Os testes são a fonte da verdade para os critérios de aceitação

3. Identificar Limites de Capacidade

Procure por limites de capacidade, não limites de artefatos de código.

Limites bons:

• Um novo módulo com seus tipos, implementação e testes juntos
• Uma capacidade visível ao usuário (ex.: um novo comando CLI)
• Um requisito sendo satisfeito de ponta a ponta

Anti-padrão: Dividir por artefato (tipos em um commit, implementação em outro, testes em um terceiro).

4. Construir o Grafo de Dependências

Para cada commit, liste quais commits devem ser concluídos primeiro. Codifique como tabela [dependencies] onde a chave é o ID do commit e o valor é a lista de IDs de dependência.

O orquestrador usa isso para determinar a execução paralela.

5. Mapear Testes para Commits

Para cada commit, liste os nomes específicos dos testes de test-plan.md que o verificam:

tests = [
  "test_protocol_encode_acquire_request",
  "test_protocol_decode_roundtrip",
]

Todo teste em test-plan.md deve aparecer no array tests de exatamente um commit.

Isso cria uma trilha auditável: test-plan.md → implementation-plan.toml → código.

6. Extrair Restrições Críticas

Para cada commit, copie as entradas relevantes da tabela de Restrições Críticas do design:

• acceptance = critérios que DEVEM ser atendidos (referencie CC-N e nomes de teste)
• anti_patterns = o que os revisores devem rejeitar

7. Escrever Entradas de Commit

Para cada commit:

[[commits]]
id = N                    # Inteiro sequencial
title = "..."             # O que este commit realiza
message = "..."           # Mensagem de commit convencional completa
files = ["..."]           # Caminhos relativos ao workspace
acceptance = ["..."]      # Da tabela CC + descrições de teste
anti_patterns = ["..."]   # Da tabela CC, ou vazio []
tests = ["..."]           # Nomes de teste de test-plan.md (OBRIGATÓRIO)

8. Verificar com Agente Independente

Após rascunhar o plano, dispare um agente de verificação:

result = spawn(
    prompt=draft_spawn_prompt(SkillDefined(
        "Verificar se o plano de implementação cobre todos os testes de test-plan.md"
    )),
    context_files=[
        f"{skill_dir}/agents/verifier.md",
        f"{feature_dir}/test-plan.md",
        f"{feature_dir}/implementation-plan.toml",
    ],
    response_model=VerificationResult,
    read_only=True,
)

if not result.parsed.valid:
    # Corrigir lacunas antes de prosseguir
    agent_feedback(f"Plano incompleto: {result.parsed.gaps}")

O verificador checa:

• Se todo teste em test-plan.md está atribuído a um commit
• Se nenhum teste está atribuído a múltiplos commits
• Se os critérios de aceitação referenciam testes específicos

9. Validar TOML

# Verificar se o TOML é válido
python3 -c "import tomllib; tomllib.load(open('implementation-plan.toml', 'rb'))"

Diretrizes de Tamanho de Commit

Alvo: 200-400 linhas alteradas por commit

Muito Pequeno:

• Tipos sem implementação
• Traits sem pelo menos uma impl
• Implementação sem testes

Muito Grande:

• Múltiplas capacidades não relacionadas
• Mais de 500 linhas
• Toca mais de 5-6 arquivos

Na Medida Certa:

• Um módulo com tipos, impl e testes (~200-400 linhas)
• Um comando CLI com handler e testes (~150-350 linhas)
• Um adaptador completo com testes (~200-400 linhas)

Modelo de Verificação

from pydantic import BaseModel

class VerificationResult(BaseModel):
    valid: bool
    total_tests_in_plan: int
    tests_assigned: int
    gaps: list[str]  # Testes não atribuídos a nenhum commit
    duplicates: list[str]  # Testes atribuídos a múltiplos commits

Exemplo

Consulte docs/features/0000-templates/implementation-plan.toml para um exemplo completo.

Próximos Passos

Após criar e verificar o plano:

1. Revise a viabilidade e o dimensionamento
2. Execute o skill implement-commit para colocar em prática