rtaffe28/arch-plan

Plano com arquitetura em primeiro lugar

O plano responde a duas perguntas acima de tudo: quais são as peças e como elas se conectam (diagramas), e quais são os contratos exatos entre elas (interfaces). Listas de tarefas são secundárias; um implementador competente pode derivá-las de boas interfaces.

Os planos são locais e pessoais: ~/plans/<YYYY-MM-DD>-<slug>/. O arquivo markdown é a fonte da verdade. O Artefato é uma visão dele.

1. Entender a solicitação

• Reformule o objetivo em uma ou duas frases, além do que está explicitamente fora do escopo.
• Se os requisitos são ambíguos, pergunte (veja Fazendo perguntas abaixo). Pergunte apenas o que mudaria o design. Faça outra rodada se as respostas abrirem novos caminhos.
• Quando uma boa opção padrão depende do que o código já faz, faça uma passagem rápida do passo 2 primeiro, para que suas recomendações sejam baseadas no repositório, e não em suposições.

Fazendo perguntas

Toda pergunta ao usuário, neste passo, após o debate, e ao iterar, é feita através da ferramenta AskUserQuestion, nunca como uma lista no chat. O usuário deve ser capaz de responder a maioria com um clique:

• Pré-preencha uma recomendação. Torne a opção que você escolheria a primeira, com (Recomendado) no final do seu rótulo. Baseie-a nos padrões existentes do código, AGENTS.md, e no que mantém o design mais simples.
• 2–4 opções concretas por pergunta, cada uma uma escolha real, com uma descrição que diz o que significa para o design (ex.: "adiciona uma migração", "reutiliza useCursorFeed"). Não adicione uma opção "Outro": a ferramenta adiciona uma para texto livre.
• Autossuficiente. O usuário pode ver apenas o diálogo, então cada pergunta nomeia a funcionalidade e a coisa que está sendo decidida, e diz brevemente o que você encontrou se é isso que motiva a pergunta.
• Até 4 perguntas por chamada, com um header curto para cada (≤12 caracteres, ex.: "Armazenamento", "Autenticação", "Escopo"). Agrupe perguntas relacionadas; faça outra chamada para o restante.
• Use multiSelect apenas quando as opções não são exclusivas (ex.: "quais superfícies recebem isso?"). Use preview ao comparar artefatos concretos: um esboço de interface, um esquema, um layout ASCII.
• Se você tem uma resposta clara e a escolha é barata de reverter, não pergunte: decida, e registre na tabela de decisões.

2. Coletar contexto

No phave-ng (o checkout principal ou a worktree da stack):

• Leia CLAUDE.md, AGENTS.md, e .claude/rules/* primeiro. Eles codificam decisões que você não deve contradizer.
• Descubra o que existe: os tipos, serviços, rotas, tabelas, jobs e componentes que a funcionalidade toca ou pode reutilizar. Para uma varredura ampla, execute agentes Explore em paralelo, um por área, e mantenha apenas suas conclusões.
• Anote cada interface existente que você estenderá, com seu caminho:linha.

3. Dimensionar

	Pequeno	Grande
Sinais	Uma área do código, aproximadamente um PR (abaixo de ~400 linhas), sem migração ou uma trivial	Várias áreas, mudanças de esquema, novos jobs em segundo plano, mais de um PR, ou várias pessoas ou sessões
Saída	Apenas plan.md	plan.md mais slices/01-<nome>.md, slices/02-<nome>.md, ...

Não divida trabalho pequeno. Cerimônia em uma mudança de um PR é desperdício.

Para trabalho grande, corte fatias verticais: cada fatia é integrável por si só, deixa o main funcionando e entrega algo testável. Uma "fatia" apenas de esquema ou uma "fatia de frontend" não é uma fatia. Ordene as fatias por dependência e mantenha cada uma aproximadamente um PR.

4. Escrever o plano

~/plans/<data>-<slug>/plan.md:

# <Título>

**Status:** Rascunho | Aprovado | Em andamento | Concluído
**Tamanho:** Pequeno | Grande (N fatias)
**Repositório / base:** phave-ng @ <commit>

## Objetivo
<2–3 frases> · **Fora do escopo:** <itens>

## Arquitetura
### Componentes
<Fluxograma Mermaid: peças existentes em estilo simples, novas peças destacadas, peças alteradas marcadas>
### Fluxos principais
<Diagrama de sequência Mermaid para cada fluxo importante, incluindo o principal caminho de erro>
### Modelo de dados
<Diagrama ER Mermaid se tabelas ou colunas mudarem; diagrama de estado se algo tiver um ciclo de vida>

## Interfaces
<Todo contrato que a funcionalidade adiciona ou altera, como código real na linguagem do repositório.
 Marque cada um como NOVO ou ALTERADO, com seu caminho de arquivo alvo.>
- Tipos / modelos de domínio
- Funções e serviços: assinaturas completas, além do que eles lançam
- HTTP / actions de servidor: método, caminho, tipos de requisição e resposta, autenticação, códigos de erro
- Banco de dados: tabelas, colunas, índices, política RLS, nome da migração
- Jobs / eventos: nome, tipo do payload, idempotência, retentativas
- Componentes de IU: props, e qual página os renderiza

## Principais decisões de design
| Decisão | Opções consideradas | Escolhida | Por que |

## Perguntas em aberto
- [ ] <pergunta> — quem pode respondê-la, e o que muda dependendo da resposta

## Fatias        (apenas grande)
| # | Fatia | Entrega | Depende de | Status |

## Plano (apenas pequeno)
<Passos ordenados; para cada: as interfaces que implementa, arquivos, e como é testado>

## Estratégia de teste
<O que é testado unitariamente e o que é testado contra uma stack (veja `ai-test` / `manual-test`)>

## Riscos

Cada slices/0N-<nome>.md tem: objetivo, as interfaces de plan.md que implementa (link para elas, não copie), arquivos, passos ordenados, critérios de aceitação, testes, e Notas de implementação (deixadas vazias, preenchidas por implement-plan).

Regras:

• Diagramas são Mermaid, com uma ideia por diagrama. Se um precisar de mais de ~12 nós, divida-o.
• Interfaces são código, não prosa. Nomeie arquivos reais. Reutilize tipos existentes onde puder, e diga isso.
• Toda decisão que um engenheiro razoável poderia tomar de forma diferente vai na tabela de decisões.
• Desconhecidos vão em Perguntas em aberto, cada uma com a resposta que você recomendaria. Não adivinhe silenciosamente.

5. Debate crítico / defensor

Lance dois agentes em paralelo com a ferramenta Agent. Dê a cada um o caminho do plano e os principais arquivos do repositório para ler, não suas conclusões:

• Crítico: "Encontre o que está errado. O design atende ao objetivo? As interfaces estão faltando, são vazadas ou inconsistentes com os padrões do código? As fatias não são verdadeiramente verticais? Há uma parte superprojetada ou subespecificada, uma reutilização perdida, um modo de falha, um risco de migração, uma lacuna de permissões? Relate cada problema com uma correção concreta."
• Defensor: "Faça o caso mais forte para as escolhas do plano, especialmente onde a alternativa óbvia foi rejeitada. Nomeie o que o crítico provavelmente atacará e por que o design atual se sustenta."

Em seguida, uma rodada de réplica: envie a cada agente a saída do outro (SendMessage) e peça que ele ceda ou mantenha cada ponto, com razões.

Você é o juiz. Para cada ponto de contenção:

• Mudança acordada: aplique em plan.md / arquivos de fatia.
• Não resolvido, e precisa do usuário: mova para Perguntas em aberto, com a opção que você recomendaria.
• Rejeitado: mantenha a decisão, e registre o porquê na tabela de decisões.

Acrescente um ## Sumário do debate a plan.md: ponto → crítico → defensor → resolução.

6. Apresentar como um Artefato

Carregue artifact-design, e artifact-diagramming para os diagramas. Publique uma página para revisão, nesta ordem:

1. Título, status, tamanho e um resumo de um parágrafo
2. Principais decisões de design (a tabela)
3. Perguntas em aberto: o que você precisa do usuário, de primeira classe e fácil de encontrar
4. Diagramas de arquitetura, renderizados, não texto Mermaid bruto
5. Interfaces, como código destacado, agrupadas por camada, com badges NOVO / ALTERADO
6. Fatias (grande) ou passos (pequeno)
7. Destaques do debate: apenas os pontos que mudaram o plano ou ainda estão abertos
8. O caminho local de plan.md

No chat, forneça o link. Em seguida, faça as perguntas em aberto com AskUserQuestion (veja Fazendo perguntas), cada uma com as posições do crítico e do defensor como opções e sua recomendação primeiro.

7. Iterar até a aprovação

As respostas e comentários do usuário vão primeiro para plan.md: perguntas respondidas passam de Perguntas em aberto para a tabela de decisões. Novas perguntas levantadas durante a iteração são feitas da mesma forma, com AskUserQuestion e uma opção recomendada. Em seguida, republique o mesmo Artefato (mesmo caminho de arquivo, para que a URL permaneça a mesma). Quando o usuário aprovar, defina Status: Aprovado e aponte-o para implement-plan.

Não escreva código de produto neste skill.