116 lines
6.1 KiB
Markdown
116 lines
6.1 KiB
Markdown
---
|
|
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 <instrução ou descrição da melhoria / bug>
|
|
|
|
# 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 <slug> # 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 <slug-ou-nome-do-arquivo>
|
|
```
|
|
|
|
> 💡 **Nota de Compatibilidade:** Caso o operador invoque a sintaxe `/plano executar <slug>`, o agente automaticamente acionará o procedimento canônico de [`/plano.executar`](../plano.executar/SKILL.md).
|
|
|
|
---
|
|
|
|
## 🛠️ Procedimento Operacional: Criação de Plano (`/plano <instrução>`)
|
|
|
|
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-<slug>.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-<slug>
|
|
titulo: "<Título claro e direto>"
|
|
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:
|
|
- <PACOTE-1>
|
|
- <PACOTE-2>
|
|
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-<slug>.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 <slug>` (plano específico)
|
|
- `/plano.executar todos` (processamento serial em ordem de chegada FIFO com circuit breaker)
|
|
|
|
---
|
|
|
|
## 🛠️ Procedimento Operacional: Arquivamento Manual (`/plano arquivar <slug-ou-id>`)
|
|
|
|
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.
|