AgentDock (Pontos de Ancoragem do Agente)

AgentDock (Brainstorm Trellis)

Contrato de Planejamento Inegociável

Um pedido para construir, implementar, corrigir, refatorar ou "ir em frente" não é aprovação para pular o planejamento. O consentimento para criar uma tarefa também não é aprovação para implementação.

Para cada tarefa não trivial, o usuário deve responder pelo menos uma vez após o pedido inicial antes que a implementação comece. Se nenhum esclarecimento for necessário, essa resposta deve aprovar o resumo final do planejamento descrito abaixo.

Enquanto qualquer decisão de produto, escopo, UX, compatibilidade, risco ou aceitação pertencente ao usuário permanecer não resolvida, termine o turno com exatamente uma pergunta de maior valor. Não edite código de produto, execute a implementação ou rode task.py start.

Regra de Evidência Inegociável

Se uma pergunta pode ser respondida explorando o código-fonte, explore o código-fonte.

Isto é obrigatório. Antes de perguntar ao usuário, verifique primeiro se a resposta já está disponível no código, testes, configurações, documentação, especificações existentes ou histórico de tarefas.

Não pergunte ao usuário para confirmar fatos que o repositório pode responder. Pergunte apenas sobre intenção de produto, preferência, escopo, tolerância a risco, comportamento de aceitação ou decisões que permanecerem ambíguas após a inspeção.

A evidência do repositório estabelece o comportamento atual e as restrições técnicas. O comportamento pretendido pelo usuário, os limites do escopo do recurso e as preferências de UX nunca são respondíveis apenas pela evidência do repositório, mesmo quando um padrão existente está presente; padrões existentes são opções e evidências de recomendação, não decisões.

---

Use esta skill durante o Planejamento da Fase 1 para transformar a solicitação do usuário em requisitos claros e artefatos de planejamento.

Pré-condições

Use esta skill somente após o consentimento para criar a tarefa ter sido dado e o usuário estiver pronto para entrar no planejamento do Trellis.

Se a tarefa ainda não existir, crie uma:

TASK_DIR=$(python3 ./.trellis/scripts/task.py create "<título curto da tarefa>" --description "<resumo de uma linha>" --slug <slug>)

Use um título conciso a partir da solicitação do usuário. Tanto o título quanto o --description devem ser não vazios — o create rejeita espaços em branco, e um registro com qualquer um deles vazio é recusado no arquivamento. Use um slug sem prefixo de data. O task.py create adiciona automaticamente o prefixo de diretório MM-DD-.

O task.py create cria o prd.md padrão. Atualize esse arquivo com o entendimento atual antes de fazer perguntas de acompanhamento.

Fluxo de Planejamento

1. Capture a solicitação do usuário e os fatos iniciais conhecidos em prd.md.
2. Inspecione as evidências disponíveis antes de fazer perguntas:
   • código, testes, fixtures e configurações
   • arquivos README, documentação, especificações existentes e notas de domínio
   • tarefas Trellis relacionadas, arquivos de pesquisa e histórico de sessão, quando presentes
3. Separe o que você encontrou em:
   • fatos confirmados
   • intenção de produto ainda necessária do usuário
   • decisões de escopo ou risco ainda necessárias do usuário
   • itens provavelmente fora do escopo
4. Se uma decisão pertencente ao usuário permanecer, faça a única pergunta de maior valor, inclua sua recomendação e trade-off, e então pare. Não realize trabalho de implementação no mesmo turno.
5. Após cada resposta do usuário, atualize o prd.md, recalcule o inventário de decisões e repita a partir do passo 2.
6. Quando nenhuma decisão pertencente ao usuário restar, crie ou atualize design.md e implement.md para tarefas complexas.
7. Execute o portão de convergência de requisitos e, em seguida, a passagem de convergência do PRD.
8. Apresente o resumo final do planejamento e pare. Não execute task.py start nem edite código de produto no mesmo turno.
9. Apenas uma mensagem subsequente do usuário que aprove explicitamente o resumo final do planejamento autoriza task.py start e a implementação. Se os artefatos mudarem materialmente após a aprovação, repita a revisão final.

Não invente uma hierarquia de produto/especificação específica do projeto. Se o repositório já tiver documentos de produto, domínio ou especificações, use-os. Se não tiver, prossiga com as evidências que existem.

Regras de Perguntas

Faça apenas uma pergunta por mensagem.

Cada pergunta deve incluir:

• a decisão necessária
• por que a resposta é importante
• sua resposta recomendada
• o trade-off se o usuário escolher de forma diferente

Não faça perguntas de processo, como se deve pesquisar, inspecionar arquivos ou continuar o brainstorming. Faça o trabalho de evidência diretamente. Pergunte ao usuário somente quando o problema restante for uma decisão de produto, preferência, limite de escopo ou escolha de tolerância a risco.

Recomendações não são seleções padrão. Nunca escolha uma decisão de produto recomendada em nome do usuário meramente porque o usuário pediu implementação.

Não fabrique perguntas de esclarecimento quando a solicitação e as evidências do repositório já resolverem todas as decisões. Nesse caso, prossiga diretamente para o resumo final do planejamento, que ainda requer uma aprovação explícita subsequente.

A revisão final é um portão de transição de fase obrigatório, não uma pergunta de processo proibida. O consentimento para criar a tarefa, o pedido inicial de implementação e a aprovação dada antes do resumo final mais recente não satisfazem este portão.

Estrutura de Pensamento: Análise de Primeiros Princípios

Quando os requisitos são vagos, as soluções parecem superdimensionadas ou você está prestes a adicionar complexidade "porque todo mundo faz" — decomponha em verdades fundamentais antes de raciocinar para cima.

Passo 1: Reformule o Problema

Remova os detalhes de implementação para uma frase.

Ruim: "Precisamos adicionar cache Redis ao endpoint de perfil do usuário" Bom: "Os dados do perfil do usuário demoram muito para carregar"

Passo 2: Liste as Verdades Fundamentais

O que é absolutamente verdadeiro (não opinião ou convenção)?

Categoria	Exemplos
Restrições físicas	Latência de rede ≥ 0, I/O de disco tem limites
Regras de negócio	"Os usuários devem ver seus próprios dados"
Invariantes técnicas	"Os dados devem ser consistentes"
Necessidades do usuário	"O usuário quer X em até Y segundos"

Passo 3: Desafie Suposições

Para cada componente do plano atual:

• Fato ou convenção? "Sempre usamos REST" — por quê?
• E se removermos isso? Se nada quebrar, é desnecessário.
• Resolvendo o problema real ou um sintoma? Trace a cadeia causal.
• Quem se beneficia com essa complexidade? Se "ninguém", simplifique.

Passo 4: Construa a Partir das Verdades

1. Comece com o mecanismo mínimo viável que satisfaça todas as verdades
2. Adicione complexidade somente quando uma verdade específica a exigir
3. Cada adição deve responder: "Qual verdade requer isso?"

Passo 5: Valide

• A solução resolve o problema original?
• Quais suposições precisam de verificação?
• Qual é o experimento mais simples para testar isso?

Portão de Convergência de Requisitos

Antes da revisão final, verifique todos os itens a seguir:

• o resultado do usuário e o valor do produto estão explícitos
• o comportamento dentro e fora do escopo está explícito
• os critérios de aceitação descrevem resultados observáveis
• as decisões de produto, escopo, UX, compatibilidade e risco pertencentes ao usuário estão resolvidas
• as perguntas em aberto que bloqueiam estão vazias
• as incógnitas técnicas são pesquisadas ou explicitamente adiadas sem alterar o comportamento do MVP

Tarefas leves podem omitir design.md e implement.md; elas não podem pular a inspeção de evidências, a convergência de requisitos, a revisão final ou a aprovação de implementação renovada.

O resumo final do planejamento deve mostrar Meta, Dentro do Escopo, Fora do Escopo, Critérios de Aceitação, Decisões Principais, Riscos ou Itens Adiados relevantes e o status dos artefatos.

Regras de Artefatos

prd.md registra requisitos e aceitação:

• meta e valor do usuário
• fatos confirmados
• requisitos
• critérios de aceitação
• fora do escopo
• perguntas em aberto que ainda bloqueiam o planejamento

design.md registra o design técnico para tarefas complexas:

• arquitetura e limites
• fluxo de dados e contratos
• notas de compatibilidade e migração
• trade-offs importantes
• considerações operacionais ou de reversão

implement.md registra o planejamento de execução para tarefas complexas:

• lista de verificação de implementação ordenada
• comandos de validação
• arquivos arriscados ou pontos de reversão
• verificações de acompanhamento antes do task.py start

Tarefas leves podem ter apenas prd.md. Tarefas complexas devem ter prd.md, design.md e implement.md antes do task.py start.

O implement.md não substitui o implement.jsonl. Em fluxos de trabalho com despacho de subagentes, tanto implement.jsonl quanto check.jsonl devem conter pelo menos uma entrada real de especificação/pesquisa antes do task.py start; um manifesto vazio, ou que contenha apenas uma linha reservada de exemplo _example legada, não conta. Fluxos de trabalho inline pulam este portão JSONL porque a Fase 2 carrega o contexto através do trellis-before-dev.

Passagem de Convergência do PRD

Antes de declarar o planejamento pronto ou executar task.py start, reescreva o prd.md uma vez de acordo com a estrutura final descrita nas regras de artefatos acima. Isso não é uma limpeza opcional; é o portão final do planejamento.

A passagem deve ser sem perdas:

• Agrupe fatos repetidos em uma seção com autoridade.
• Dobre seções temporárias de brainstorming, como "O que já sei", "Suposições" e "Perguntas em aberto" resolvidas em Meta, Contexto, Requisitos, Notas Técnicas ou Critérios de Aceitação.
• Remova perguntas em aberto resolvidas em vez de deixar seções vazias ou já respondidas.
• Mescle listas paralelas de bugs e requisitos quando descreverem o mesmo trabalho; mantenha a severidade de cada defeito, evidência e âncoras de arquivo:linha no requisito proprietário.
• Preserve cada âncora de arquivo:linha, decisão, restrição, ID de requisito e mapeamento de critérios de aceitação.
• Não prossiga para a revisão final enquanto houver alguma pergunta em aberto que bloqueia.

Após a passagem, leia o prd.md de cima a baixo e verifique se nenhum fato é repetido entre as seções, a menos que a repetição adicione novas informações.

Padrão de Qualidade

Antes de declarar o planejamento pronto:

• prd.md contém critérios de aceitação testáveis.
• prd.md passou pela passagem de convergência do PRD: sem seções temporárias de brainstorming não resolvidas, sem fatos duplicados entre as seções e sem âncoras, decisões ou mapeamentos de aceitação perdidos.
• Perguntas respondíveis pelo repositório já foram respondidas através de inspeção.
• Perguntas em aberto que bloqueiam estão vazias.
• Tarefas complexas têm design.md e implement.md.
• Tarefas com despacho de subagentes têm entradas reais curadas em ambos implement.jsonl e check.jsonl; manifestos apenas com sementes não estão prontos.
• O resumo final do planejamento mais recente foi apresentado ao usuário.
• Em uma mensagem subsequente, o usuário aprovou explicitamente esse resumo para implementação.

Não comece a implementação meramente porque o usuário pediu implementação originalmente.