snuffish/plan

Skill: /plan — Gerenciador de Plano de Implementação

Gerencia o plano de implementação ativo (<prefix>-implementation_plan-<suffix>.md) para a sessão. Esta skill é responsável pelo esqueleto do plano, seus valores de status, seu bloco de links e sua revisão (--review). Todos os outros comandos que escrevem ou leem um plano (/implement-feature, /problem, /refine, /pr-fix-pipeline, /proceed) usam as definições aqui.

---

Módulos

Os caminhos são relativos à pasta real desta skill. Execute realpath no diretório base da skill uma vez (pode ser um link simbólico) e, em seguida, resolva cada caminho a partir daí. Se algum Módulo não puder ser lido, pare e informe o caminho. Não continue sem ele.

Leia estes antes da etapa 1:

• ../_modules/core.md
• ../_modules/artifact-protocol.md: escreve <prefix>-implementation_plan-<suffix>.md no diretório de artefatos (artifact-protocol)
• ../_modules/project-profile.md: apenas perfil base (nenhum perfil de Comando), para a revisão (Caso D); lê Referências por camada, Pontos de contato do contrato, Cadeia irmã e um campo opcional Verificações de revisão do plano

Referências sob demanda (references/):

• references/review.md — cinco pilares de revisão (Caso D etapa 3) e modelo de relatório para --review (Caso D) e autorrevisão (Caso B etapa 4)

---

1. O Contrato do Plano

Valores de status

A segunda linha de um plano carrega **Status:** <valor>, com um dos seguintes:

Valor	Significado	Definido por
Draft	Sendo escrito; não pronto para revisão	O escritor, durante o rascunho
Awaiting User Review	Completo e aguardando no portão	O escritor, ao apresentá-lo
Approved	O usuário abriu o portão; a implementação está em execução	core › O portão /proceed
Completed	Todas as fases no escopo foram concluídas e verificadas	core › O portão /proceed

Uma breve nota pode seguir o valor (Approved — fase 2 de 3 concluída). Os leitores consideram apenas o valor principal.

Esqueleto

<!-- artifact-owner: … -->                 <!-- artifact-protocol › Claim -->

# Plano de Implementação: <título>

**Status:** Awaiting User Review
**Suffix:** `<suffix>`
**Inputs:** <links de investigação / revisão / tickets, ou "none">
**Review:** <veredito do _Caso D_ após incorporação> · <n> descobertas incorporadas <!-- Caso B etapa 4 -->

## 1. Contexto e Objetivo

## 2. Decisões <!-- tabela: decisão · motivo -->

## 3. Mudanças Propostas <!-- por fase ou por repositório: [NEW|MODIFY|DELETE] <caminho> — o que e por que -->

## 4. Plano de Verificação <!-- comandos exatos, mais etapas manuais -->

## 5. Riscos <!-- tabela: risco · mitigação -->

## 6. Lista de Tarefas <!-- a lista de verificação ativa: [ ] / [/] / [x] -->

## 7. Perguntas em Aberto <!-- perguntas não resolvidas; sempre por último, se houver; cada uma com uma recomendação -->

Um Comando pode adicionar seções que precisar (/implement-feature adiciona Revisão do Usuário Necessária, Passagem de Pontos Cegos e Ordem entre Repositórios). Ele mantém estas sete, nessa ordem, para que /plan, /plan --review e /proceed possam encontrá-las. Perguntas em Aberto (perguntas não resolvidas) é sempre a última seção; uma seção adicionada vem antes dela.

Estilo

A regra do usuário (~/.claude/CLAUDE.md › Modo Plano) se aplica: extremamente conciso, gramática sacrificada; termine com Passos, depois Perguntas não resolvidas (cada uma com uma recomendação, omitida quando não houver).

Todo escritor de plano o aplica ao arquivo inteiro e à resposta no chat que apresenta o plano:

• Fragmentos, não prosa: sem parágrafos, sem explicações em frases completas.
• Uma ideia por marcador; divida um mais longo em submarcadores.
• Decisões e Riscos como tabelas.
• Toda pergunta em aberto carrega Rec: com a resposta recomendada.
• Nada depois de Perguntas em Aberto. Se não houver perguntas não resolvidas, observe "Nenhuma" (ou omita).

Bloco de links

Toda resposta no chat que apresenta um plano começa com o artifact-protocol › Bloco de links do chat (números de linha reais de grep -n '^#\{1,3\} ' <arquivo> após a escrita) vinculando Contexto e Objetivo, Mudanças Propostas, Plano de Verificação e Perguntas em Aberto, seguido por **Status:** <valor>. Um Comando pode anexar um resumo de uma linha após cada link de seção (/plan --review faz isso).

---

2. Comportamentos Principais

Escolha o caso a partir dos argumentos, a primeira correspondência vence:

Argumentos	Caso
Contêm --review	D: revisar um plano
Começam com preview	C: visualizar
Nenhum	A: básico
Qualquer outra coisa	B: rascunhar ou atualizar

Caso A: Comando Básico (/plan sem argumentos ou mensagem)

1. Localize o plano: procure por <prefix>-implementation_plan-*.md no diretório de artefatos (artifact-protocol) e selecione a família conforme artifact-protocol › Claim › Leitores e seleção de família (informe ao usuário que ele pode pular o prompt na próxima vez com /plan <suffix>). Se nenhum existir, diga isso e ofereça-se para criar um a partir do próximo prompt do usuário.
2. Renderize o bloco de links (§1 Bloco de links) para o plano escolhido, com seu Status atual. Não edite nada nem execute comandos em segundo plano.

Caso B: Comando com Instruções (/plan <instruções>)

1. Resolva o sufixo contextual conforme artifact-protocol › regra 2.
2. Planeje, sem alterar código:
   • Verifique primeiro se há uma investigação existente. Se <prefix>-investigation-<suffix>.md existir no diretório de artefatos (artifact-protocol) e cobrir este tópico, construa sobre ele: sua Semente do Plano, Opções e Trade-offs e Registro de Confiança. Não refaça pesquisas que ele já documenta; resolva qualquer ❓ Desconhecido do qual o plano dependa.
   • Caso contrário, pesquise o código relevante somente leitura. Se o tópico for grande ou as incógnitas forem substanciais, execute /investigate primeiro.
   • Projete de acordo com as próprias convenções do projeto: seus livros de regras do espaço de trabalho, Referências e Perfil de escopo do projeto (core › Precedência).
3. Escreva o plano no §1 Esqueleto, no diretório de artefatos (artifact-protocol):
   • Novo plano: rascunhe-o em um caminho privado da sessão e, em seguida, publique-o com Claim (artifact-protocol › regra 4). Se o nome base já estiver ocupado, a Claim escreve …-2.md; use o caminho que ela imprimiu e informe no chat.
   • Plano existente: atualize-o apenas se seu marcador de proprietário nomear esta sessão, ou se o usuário nomeou aquele arquivo e pediu para ele ser atualizado (artifact-protocol › regra 3). Caso contrário, escreva uma nova revisão através da Claim e vincule aquela que ela substitui em Inputs.
   • Defina Status para Awaiting User Review quando estiver completo. Sob Antigravity, ao escrever uma cópia espelhada do artefato dentro de <appDataDir>/brain/<conversation-id>/, defina UserFacing = true e RequestFeedback = true em ArtifactMetadata (omita ArtifactMetadata no arquivo do diretório de artefatos).
4. Auto-revisão antes de apresentar: leia references/review.md e execute as etapas 2–3 do Caso D no plano recém-escrito, no contexto principal. Use seus pilares e gravidades. Não imprima seu relatório nem seu portão: isso é parte do rascunho, e o usuário revisa o plano incorporado.

   • Incorpore cada descoberta no plano antes de apresentar:

     Descoberta	Vai para
     🔴 / 🟡, verificada (path:line reaberto)	Mudanças Propostas, Lista de Tarefas e uma verificação no Plano de Verificação que falha sem a correção
     🔴 / 🟡 que precisa de decisão do usuário	Perguntas em Aberto, com Rec:
     🟢	Aplique se for uma linha; caso contrário, descarte
     Descoberta rejeitada	Riscos, uma linha com o motivo

   • Releia o plano uma vez para verificar se algo que uma correção contradiz (uma etapa anterior, um teste, uma linha de decisão) e corrija.

   • Execute a revisão uma vez. Preencha a linha de cabeçalho Review: com o veredito que o plano incorporado obteria.

   • Execute-a em todo novo plano e em toda atualização que altere Mudanças Propostas ou Plano de Verificação. Pule para atualizações que apenas marquem itens da lista ou alterem o Status.

5. Apresente o plano: o bloco de links (§1 Bloco de links), o veredito da revisão e as descobertas que mudaram o design (um marcador cada), as decisões principais como marcadores fragmento, depois as perguntas em aberto por último, cada uma com sua Rec: (§1 Estilo se aplica a este texto do chat também: sem parágrafos, sem frases completas). Aguarde o usuário abrir o portão (core › O portão /proceed) antes de qualquer alteração de código.

Caso C: Comando de Visualização (/plan preview [alvo])

Mostra um plano existente no painel de visualização de planejamento do host (usando ExitPlanMode quando disponível), para que o usuário possa ler, comentar e aprová-lo interativamente.

1. Resolva o plano: Use o argumento (caminho ou sufixo), o arquivo de plano ativo da sessão ou a família de planos mais recente no diretório de artefatos (Caso A).
2. Verificação de capacidade do host: Se o host não tiver ExitPlanMode (como o Antigravity IDE), produza o bloco de links do plano (Caso A) e explique que o host renderiza planos diretamente via links markdown.
3. Entre no modo de plano e copie: Chame EnterPlanMode, leia o caminho do arquivo de plano do host a partir da mensagem do sistema e copie o plano de origem para lá (omitindo o comentário inicial <!-- artifact-owner: … -->).
4. Abra a visualização: Chame ExitPlanMode.
5. Lide com a decisão:
   • Aprovar: O usuário autorizou a implementação (core › O portão /proceed). Inicie a execução.
   • Continuar planejando / Feedback: Permaneça no modo de plano, passe o feedback para o Caso B atualizar o plano e reabra a visualização.
   • Fechado / Erro: Informe o status e forneça o link do arquivo.

Caso D: Comando de Revisão (/plan --review [alvo])

Auditoria estrita e somente leitura de um plano de implementação, proposta arquitetural ou design de mudança, antes que qualquer código seja escrito. Somente leitura até /proceed (core › O portão /proceed):

• Nunca edite arquivos, execute comandos de modificação (migrações, commits, scaffolding) ou comece a implementar, mesmo quando o plano estiver impecável.
• Toda resposta sob --review, incluindo acompanhamentos, começa com o bloco de links: o usuário frequentemente fecha a aba do plano e a reabre a partir do chat.

Ferramenta errada:

Situação	Use em vez disso
Um diff de código, branch ou PR em vez de um plano	/code-review
Comentários e votos de revisor em um PR	/pr-feedback-review
Pesquisa antes de um plano existir	/investigate
Suposições ocultas e modos de falha de um design	/what-am-I-missing

Leia references/review.md e execute as etapas 1–4 do Caso D (etapa 1: localizar plano; etapa 2: ler regras do projeto; Caso D etapa 3: avaliar contra os cinco pilares + perfil Verificações de revisão do plano; etapa 4: renderizar bloco de links e relatório de revisão), então aguarde em core › O portão /proceed.