--- name: plano description: Criar e gerenciar planos técnicos de implementação em ./PLANOS/pendente/ gerados por testers e executados por devs scope: global updatedAt: "2026-09-30" --- # Skill: /plano (Criação e Gestão de Planos Técnicos) Esta skill capacita o agente a atuar como ponte técnica entre o **Tester / QA** e o **Desenvolvedor**, formalizando demandas de homologação em planos de implementação completos na pasta `./PLANOS/pendente/` sem interromper a rotina de testes. Para a fase de implementação e codificação, aciona-se a skill dedicada [`/plano.executar`](../plano.executar/SKILL.md). --- ## 🎯 Gatilhos e Comandos ```bash # 1. Criação de novo plano técnico (Fase de Tester / Review) /plano # 2. Listagem e panorama da fila de planos /plano listar # 3. Execução pelo Desenvolvedor (Comando Canônico Dedicado) /plano.executar # Executa o último plano da conversa ou mais recente /plano.executar # Executa plano específico por slug/ID /plano.executar todos # Executa todos os pendentes em lote serial (ordem de chegada - FIFO) # 4. Arquivamento manual de um plano já concluído /plano arquivar ``` > 💡 **Nota de Compatibilidade:** Caso o operador invoque a sintaxe `/plano executar `, o agente automaticamente acionará o procedimento canônico de [`/plano.executar`](../plano.executar/SKILL.md). --- ## 🛠️ Procedimento Operacional: Criação de Plano (`/plano `) Quando invocado com uma instrução (ex.: `/plano corrigir validação do número do processo no formulário de denúncia`): ### 1. Obter Data, Hora e Gerar Slug - Obtenha a data e hora locais atuais da máquina no formato `AAAA-MM-DD-HH-mm` (ano com 4 dígitos, mês, dia, hora 24h e minuto com 2 dígitos, ex.: `2026-09-30-10-35`). - Converta o tema principal da instrução em um slug sucinto em kebab-case (letras minúsculas e hífens, sem acentos ou caracteres especiais). - Caminho alvo: `./PLANOS/pendente/AAAA-MM-DD-HH-mm-.md`. - **Propósito da Nomenclatura:** A inclusão de hora (`HH`) e minuto (`mm`) no prefixo temporal viabiliza a ordenação lexicográfica determinística da fila (FIFO — First In, First Out), permitindo que `/plano.executar todos` processe os planos estritamente na ordem em que foram criados. ### 2. Diagnóstico Técnico Pré-Implementação (Sem alterar código) - **NÃO altere arquivos de código de produção nesta etapa.** - Mapeie os pacotes afetados (`*-comuns`, `*-back`, `*-front`, `*-migracao`). - Inspecione rapidamente arquivos relevantes com `view_file` ou `grep_search` para identificar a causa raiz, props, schemas Zod, rotas ou componentes envolvidos. - Identifique o comportamento atual vs comportamento esperado. ### 3. Redigir e Persistir o Arquivo de Plano - Garanta que o diretório `./PLANOS/pendente/` existe. - Baseie-se no template canônico `.agent/DOCUMENTACAO/templates/plano.md.template`. - Preencha o arquivo com: - **Frontmatter YAML:** ```yaml --- id: AAAA-MM-DD-HH-mm- titulo: "" origem: "Revisão Tester / QA" data-criacao: "AAAA-MM-DD HH:mm" data-execucao: null status: "pendente" prioridade: "media" # ou critica/alta/baixa tipo: "bug" # ou melhoria/feature/ux/refatoracao modulos-impactados: - - executor: null --- ``` - **1. Objetivo & Contexto:** Descrição concisa da demanda e impacto de negócio. - **2. Diagnóstico Técnico & Evidências:** Comportamento observado vs esperado, repro steps e arquivos mapeados com links `[arquivo](file://...)`. - **3. Critérios de Aceite & Validação (DoD):** Checklist com caixas `- [ ]` contendo condições verificáveis de sucesso. - **4. Especificação Técnica & Passos de Implementação:** Roteiro prático para o desenvolvedor (schemas, backend, frontend, código sugerido). - **5. Plano de Verificação & Testes:** Testes automatizados (`typecheck`, `biome`) e roteiro manual/E2E com `agent-browser`. - **6. Histórico de Execução:** Cabeçalho reservado para preenchimento na conclusão pelo executor. - Salve o arquivo em `./PLANOS/pendente/AAAA-MM-DD-HH-mm-.md` usando `write_to_file`. ### 4. Resposta ao Usuário - Informe o link do arquivo criado em `./PLANOS/pendente/`. - Apresente um resumo sucinto dos módulos impactados e critérios de aceite. - Sinalize que o plano está na fila e que o tester pode continuar a homologação criando novos planos com `/plano` ou solicitar a implementação via `/plano.executar`. --- ## 🛠️ Procedimento Operacional: Listagem (`/plano listar`) 1. Liste os arquivos existentes em `./PLANOS/pendente/` e `./PLANOS/executado/`. 2. Para cada arquivo, extraia título, data e prioridade do frontmatter. 3. Exiba uma tabela Markdown organizada: - **Planos Pendentes (Aguardando Dev — Fila FIFO):** ID, Título, Prioridade, Data de Criação. Listados em ordem cronológica de chegada (mais antigo primeiro). - **Planos Executados (Concluídos):** ID, Título, Data de Execução, Executor. 4. Lembre o operador dos atalhos de execução: `/plano.executar` ou `/plano.executar todos`. --- ## 🛠️ Procedimento Operacional: Execução Para implementar qualquer plano da fila, a operação canônica é delegada para: 👉 **[`skills/plano.executar/SKILL.md`](../plano.executar/SKILL.md)**: - `/plano.executar` (sem argumentos: último plano criado na conversa ou pendente mais recente) - `/plano.executar ` (plano específico) - `/plano.executar todos` (processamento serial em ordem de chegada FIFO com circuit breaker) --- ## 🛠️ Procedimento Operacional: Arquivamento Manual (`/plano arquivar `) Quando um plano foi implementado externamente ou não requer alteração de código: 1. Localize o arquivo em `./PLANOS/pendente/` (aceita slug puro, ID completo ou nome de arquivo). 2. Atualize o frontmatter para `status: "executado"`, registrando `data-execucao: "AAAA-MM-DD HH:mm"` e executor. 3. Mova o arquivo para `./PLANOS/executado/` preservando o nome original do arquivo. 4. Notifique o usuário da conclusão do arquivamento.