---
type: template
name: plano
description: Template canônico para Planos Técnicos de Implementação (fila PLANOS/pendente/ e PLANOS/executado/)
updatedAt: "2026-09-30"
---

<!--
DESTINO CANÔNICO NO PROJETO:
- Criação pelo Tester: <base_projeto>/PLANOS/pendente/AAAA-MM-DD-HH-mm-<slug>.md
- Arquivamento pelo Dev: <base_projeto>/PLANOS/executado/AAAA-MM-DD-HH-mm-<slug>.md

EXEMPLO:
PLANOS/pendente/2026-09-30-10-35-ajuste-filtro-denuncia-anonima.md
-->

---
id: AAAA-MM-DD-HH-mm-<slug-do-plano>
titulo: "<Título claro e descritivo da demanda>"
origem: "Revisão Tester / QA"
data-criacao: "AAAA-MM-DD HH:mm"
data-execucao: null
status: "pendente" # pendente | executado | cancelado
prioridade: "media" # critica | alta | media | baixa
tipo: "bug" # bug | melhoria | feature | refatoracao | ux
modulos-impactados:
  - QUIPO-BACK
  - QUIPO-FRONT
  - QUIPO-COMUNS
executor: null
---

# Plano: <Título do Plano>

## 1. Objetivo & Contexto
<Descreva o problema encontrado durante o teste ou a funcionalidade requerida. Qual é o contexto de negócio ou operacional? Por que essa mudança é necessária?>

---

## 2. Diagnóstico Técnico & Evidências do Tester

### Comportamento Observado vs Comportamento Esperado
- **Observado:** <O que acontece hoje de forma incorreta ou incompleta>
- **Esperado:** <O que deve acontecer após a implementação>

### Passos para Reproduzir (Repro Steps) / Evidência Visual
1. <Passo 1>
2. <Passo 2>
3. <Evidência: link para screenshot em evidencias/ ou anotação do tester>

### Análise de Causa Raiz & Arquivos Mapeados
<Diagnóstico técnico preliminar apontando causas prováveis no código>
- `caminho/do/arquivo1.ts` — <motivo do impacto>
- `caminho/do/arquivo2.vue` — <motivo do impacto>

---

## 3. Critérios de Aceite & Validação (Definition of Done)
- [ ] <Critério 1: Condição necessária para aceitar a entrega>
- [ ] <Critério 2: Tratamento de exceção / caso de borda>
- [ ] <Critério 3: Feedback visual na UI / resposta da API>
- [ ] <Critério 4: Ausência de efeitos colaterais em fluxos existentes>

---

## 4. Especificação Técnica & Passos de Implementação (Para o Dev)

### 4.1 Pacote `*-comuns` (se aplicável)
- Schemas Zod, tipos TypeScript ou enums a criar/ajustar.

### 4.2 Pacote `*-back` (se aplicável)
- Endpoints, controllers, queries de banco ou filas a criar/ajustar.
- Seguir regras de diagnóstico prévio (`rules/diagnostico-antes-correcao.md`) e visibilidade de erros (`rules/feedback-visivel.md`).

### 4.3 Pacote `*-front` (se aplicável)
- Telas, componentes Vue 3, composables ou estilos CSS co-localizados.
- Seguir as 12 regras de Código Limpo (`workflows/codigo-limpo.md`) e limite de 250 linhas.

### 4.4 Diffs Conceituais / Código Sugerido
```ts
// Exemplo de código ou alteração sugerida
```

---

## 5. Plano de Verificação & Testes

### 5.1 Testes Automatizados & Checagens Estáticas
- Tipagem: `bun run typecheck` ou `tsc --noEmit`
- Qualidade/Lint: `biome check --write <arquivos>`
- Governança: `sh .agent/verificar-linhas.sh`

### 5.2 Roteiro de Teste Manual / `agent-browser` (Sempre em Modo Visível `--headed` e com `--session <modulo-id>`)
1. Abrir aplicação: `agent-browser --session <modulo-id> open --headed <url>`
2. Mapear interações: `agent-browser --session <modulo-id> snapshot -i`
3. Executar ações: `agent-browser --session <modulo-id> fill @ref "..." && agent-browser --session <modulo-id> click @ref`
4. Capturar evidência: `agent-browser --session <modulo-id> screenshot evidencias/<slug>.png`
5. Encerrar: `agent-browser --session <modulo-id> close`

---

## 6. Histórico de Execução (Preenchido na Conclusão)
- **Data de Início:** `<YYYY-MM-DD HH:mm>`
- **Data de Conclusão:** `<YYYY-MM-DD HH:mm>`
- **Executor:** `<Nome do Dev ou IA>`
- **Arquivos Efetivamente Modificados:**
  - `<caminho/arquivo>`
- **Resumo da Solução Implementada:**
  - <Descrição das mudanças realizadas e desafios superados>
- **Evidências de Teste / Screenshots:**
  - <Links ou descrições dos testes executados com sucesso>