2026-09-28 11:33:26 -03:00

6 KiB

Raw Blame History

name	description	scope	updatedAt
plano	Criar e gerenciar planos técnicos de implementação em ./PLANOS/pendente/ gerados por testers e executados por devs	global	2026-09-28

Skill: /plano (Gestão e Execuçã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/ e executando-os deterministamente para posterior arquivamento em ./PLANOS/executado/.

🎯 Gatilhos e Comandos

A skill é acionada por comandos iniciando com /plano:

# 1. Criação de novo plano técnico (Fase de Tester / Review)
/plano <instrução ou descrição da melhoria / bug>

# 2. Listagem da fila de planos
/plano listar

# 3. Execução de um plano existente (Fase de Desenvolvimento)
/plano executar <slug-ou-nome-do-arquivo>

# 4. Arquivamento manual de um plano já concluído
/plano arquivar <slug-ou-nome-do-arquivo>

🛠️ 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 e Gerar Slug

Obtenha a data local atual no formato YYYY-MM-DD.
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/YYYY-MM-DD-<slug>.md.

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:
```
---
id: YYYY-MM-DD-<slug>
titulo: "<Título claro e direto>"
origem: "Revisão Tester / QA"
data-criacao: "YYYY-MM-DD"
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.
Salve o arquivo em ./PLANOS/pendente/YYYY-MM-DD-<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 ou solicitar a execução via /plano executar <slug>.

🛠️ Procedimento Operacional: Listagem (`/plano listar`)

Liste os arquivos existentes em ./PLANOS/pendente/ e ./PLANOS/executado/.
Para cada arquivo, extraia título, data e prioridade do frontmatter.
Exiba uma tabela Markdown organizada:
- Planos Pendentes (Aguardando Dev)
- Planos Executados (Concluídos)

🛠️ Procedimento Operacional: Execução (`/plano executar <slug>`)

Quando invocado para implementar um plano existente:

1. Localização e Leitura

Localize o arquivo em ./PLANOS/pendente/ correspondente ao slug fornecido.
Leia o conteúdo integral com view_file.

2. Implementação Rigorosa

Execute as mudanças solicitadas nos pacotes apropriados, seguindo:
- rules/diagnostico-antes-correcao.md
- rules/literatura-tecnica-e-usabilidade.md
- workflows/codigo-limpo.md (limite de 250 linhas por arquivo, Dispatch Tables)
- rules/feedback-visivel.md (feedback claro na UI e logs no backend)
- rules/fronteiras-monorepo.md (não vazar dependências entre back e front)

3. Validação e Qualidade

Execute checagens de integridade:
- biome check --write <arquivos-alterados>
- bun run typecheck ou tsc --noEmit (se aplicável ao pacote)
- sh .agent/verificar-linhas.sh
Valide os critérios de aceite definidos na Seção 3 do plano.

4. Transição para Executado

Atualize o conteúdo do plano:
- Frontmatter: status: "executado", data-execucao: "YYYY-MM-DD HH:mm", executor: "<nome-ou-agente>".
- Seção 6 (Histórico de Execução): registre arquivos modificados, resumo da solução e evidências de validação.
Mova o arquivo de ./PLANOS/pendente/YYYY-MM-DD-<slug>.md para ./PLANOS/executado/YYYY-MM-DD-<slug>.md (usando write_to_file no destino e removendo da pasta pendente).
Registre a ação em memorias-ia/sessao-YYYY-MM-DD-<slug>.md e indexe em memorias-ia/historico-acoes.md.
Lembre-se: nunca execute git commit na aplicação (rules/proibido-commit-ia.md). Sugira a mensagem de commit para o usuário.

🛠️ Procedimento Operacional: Arquivamento (`/plano arquivar <slug>`)

Localize o arquivo em ./PLANOS/pendente/.
Atualize o frontmatter para status: "executado" e registre a data.
Mova o arquivo para ./PLANOS/executado/.
Notifique o usuário da conclusão do arquivamento.

6 KiB Raw Blame History