130 lines
6.5 KiB
Markdown
130 lines
6.5 KiB
Markdown
---
|
|
type: workflow
|
|
name: plano
|
|
description: Workflow oficial de Gestão, Criação e Execução de Planos Técnicos (fila PLANOS/pendente/ e PLANOS/executado/)
|
|
scope: global
|
|
updatedAt: "2026-09-28"
|
|
---
|
|
|
|
# Workflow: /plano (Gestão de Planos Técnicos Tester ➔ Dev)
|
|
|
|
Workflow oficial para captura estruturada de demandas pelo **Tester / QA** durante homologações e execução determinística pelo **Desenvolvedor** no ecossistema Azteca.
|
|
|
|
> 💡 **Comandos Rápidos:**
|
|
> - `/plano <instrução>` $\rightarrow$ Diagnostica a demanda e gera um plano em `PLANOS/pendente/YYYY-MM-DD-<slug>.md`.
|
|
> - `/plano listar` $\rightarrow$ Exibe o panorama da fila de planos pendentes e executados.
|
|
> - `/plano executar <slug>` $\rightarrow$ Carrega o plano pendente, implementa o código, valida e arquiva em `PLANOS/executado/`.
|
|
> - `/plano arquivar <slug>` $\rightarrow$ Move manualmente um plano para `PLANOS/executado/`.
|
|
|
|
---
|
|
|
|
## 🎯 Por que este Workflow existe?
|
|
|
|
Durante a navegação, testes manuais ou homologação de telas e rotas, o tester frequentemente encontra inconsistências, comportamentos inesperados, melhorias visuais ou lacunas de negócio.
|
|
|
|
- **Problema anterior:** O tester precisava parar os testes para tentar implementar na hora, ou anotava observações soltas no chat que se perdiam ao final da conversa.
|
|
- **Solução com `/plano`:** O tester invoca `/plano <instrução>`. A IA analisa tecnicamente o código e materializa a demanda em um arquivo padronizado em `PLANOS/pendente/`. O tester pode criar múltiplos planos em sequência na mesma sessão de review. Mais tarde, o desenvolvedor implementa cada um deles com foco total.
|
|
|
|
---
|
|
|
|
## 🔄 Fluxo de Operação em 4 Fases
|
|
|
|
```
|
|
┌───────────────────────────┐ ┌───────────────────────────┐
|
|
│ 1. FASE DE REVIEW │ │ 2. FILA DE TRABALHO │
|
|
│ (Tester / Homologação) │ ───▶ │ (./PLANOS/pendente/) │
|
|
│ /plano <instrução> │ │ │
|
|
└───────────────────────────┘ └─────────────┬─────────────┘
|
|
│
|
|
▼
|
|
┌───────────────────────────┐ ┌───────────────────────────┐
|
|
│ 4. ARQUIVAMENTO │ │ 3. IMPLEMENTAÇÃO DEV │
|
|
│ (./PLANOS/executado/) │ ◀─── │ (Desenvolvedor / IA) │
|
|
│ Metadados & Histórico │ │ /plano executar <slug> │
|
|
└───────────────────────────┘ └───────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## 📝 Fase 1: Criação pelo Tester (`/plano <instrução>`)
|
|
|
|
Quando o comando for executado:
|
|
|
|
1. **Interpretação e Diagnóstico Rápido:**
|
|
- A IA extrai o núcleo da demanda (o que está quebrado ou precisa ser feito).
|
|
- Investiga o código-fonte (sem alterá-lo) para identificar arquivos, componentes Vue, rotas Bun/Hono, schemas Zod ou tabelas impactadas.
|
|
- Identifica a causa raiz ou o ponto exato de intervenção.
|
|
|
|
2. **Formatação do Nome do Arquivo:**
|
|
- Formato: `PLANOS/pendente/YYYY-MM-DD-<slug-em-kebab-case>.md`
|
|
- Onde `YYYY-MM-DD` é a data atual da máquina e `<slug>` reflete a essência do plano.
|
|
|
|
3. **Escrita do Documento:**
|
|
- Utiliza a estrutura do template canônico `.agent/DOCUMENTACAO/templates/plano.md.template`.
|
|
- Preenche:
|
|
- Frontmatter com `status: pendente` e tags do domínio.
|
|
- Objetivo & Contexto (visão funcional).
|
|
- Diagnóstico Técnico & Evidências (repro steps e arquivos mapeados).
|
|
- Critérios de Aceite (Definition of Done).
|
|
- Especificação Técnica passo a passo para orientar o desenvolvedor.
|
|
- Plano de Verificação & Testes.
|
|
|
|
4. **Feedback Imediato ao Tester:**
|
|
- Informa o caminho do plano gerado e confirma que o review pode prosseguir.
|
|
|
|
---
|
|
|
|
## 📋 Fase 2: Gestão da Fila (`/plano listar`)
|
|
|
|
Para visualizar o status atual de todos os planos:
|
|
- Lista arquivos em `PLANOS/pendente/` (status, título, prioridade, data).
|
|
- Lista arquivos em `PLANOS/executado/` (data de execução, executor).
|
|
|
|
---
|
|
|
|
## 💻 Fase 3: Execução pelo Desenvolvedor (`/plano executar <slug>`)
|
|
|
|
Quando o desenvolvedor (ou operador) ordenar a implementação de um plano:
|
|
|
|
1. **Carregamento do Plano:**
|
|
- A IA lê o arquivo correspondente em `PLANOS/pendente/<nome-do-arquivo>.md`.
|
|
- Se o usuário passou apenas parte do nome (ex.: `filtro-denuncia`), localiza o arquivo correspondente.
|
|
|
|
2. **Planejamento & Execução Cirúrgica:**
|
|
- Respeita as regras fundamentais:
|
|
- `rules/diagnostico-antes-correcao.md`
|
|
- `rules/literatura-tecnica-e-usabilidade.md`
|
|
- `workflows/codigo-limpo.md` (limite de 250 linhas, Dispatch Tables)
|
|
- `rules/feedback-visivel.md` (visibilidade de erros)
|
|
- `rules/fronteiras-monorepo.md` (respeitar fronteiras dos pacotes)
|
|
- Executa as alterações passo a passo nos pacotes afetados (`*-comuns`, `*-back`, `*-front`, etc.).
|
|
|
|
3. **Verificação & Testes:**
|
|
- Roda checagem de tipos (`tsc --noEmit` / `bun run typecheck`).
|
|
- Roda formatação (`biome check --write <arquivos>`).
|
|
- Roda governança de linhas (`sh .agent/verificar-linhas.sh`).
|
|
- Valida os critérios de aceite definidos na seção 3 do plano.
|
|
|
|
---
|
|
|
|
## 📦 Fase 4: Conclusão e Arquivamento (`PLANOS/executado/`)
|
|
|
|
Ao confirmar que a implementação está verde e validada:
|
|
|
|
1. **Atualização do Plano:**
|
|
- Atualiza o frontmatter do arquivo:
|
|
- `status: executado`
|
|
- `data-execucao: "YYYY-MM-DD HH:mm"`
|
|
- `executor: "<nome-do-dev-ou-agente>"`
|
|
- Preenche a Seção 6 (`Histórico de Execução`) com o resumo das modificações feitas e evidências de validação.
|
|
|
|
2. **Movimentação do Arquivo:**
|
|
- Move o arquivo de:
|
|
`PLANOS/pendente/YYYY-MM-DD-<slug>.md`
|
|
para:
|
|
`PLANOS/executado/YYYY-MM-DD-<slug>.md`
|
|
|
|
3. **Registro na Memória do Projeto (Pilar 6):**
|
|
- Cria o registro de sessão em `memorias-ia/sessao-YYYY-MM-DD-<slug>.md`.
|
|
- Indexa no `memorias-ia/historico-acoes.md`.
|
|
- Sugere o comando de commit staged para a aplicação (lembrando que commit automatizado na aplicação é proibido por `rules/proibido-commit-ia.md`).
|