lenneTech/grilling-decisions

Decisões em Aberto (Grilling)

Entreviste o usuário incansavelmente sobre um plano, tarefa ou design até que se chegue a um entendimento compartilhado. O objetivo é o alinhamento antes do início do trabalho: uma alteração construída sobre uma suposição errada custa toda a implementação, mais a revisão, o browser walk e o merge que se seguiram. Uma pergunta feita antecipadamente custa um clique; a mesma pergunta feita no meio da implementação custa a troca de contexto do usuário e interrompe a execução até que ele retorne.

Não tome nenhuma ação sobre o assunto da entrevista até que o usuário confirme que o entendimento é compartilhado.

O ciclo

1. Pesquise cada fato você mesmo (veja Fatos vs decisões). Chegue à entrevista já conhecendo o código.
2. Mapeie a árvore de decisões. Cada decisão em aberto se ramifica em decisões que dependem dela.
3. Resolva o que a tarefa e as evidências resolvem. Trabalhe cada decisão em aberto através das cinco partes de um briefing de decisão. O que a tarefa afirma claramente é registrado em suas palavras; uma lacuna que a evidência deixa exatamente uma opção é registrada com seu Beleg:; todo o resto permanece em aberto para o usuário (Resolver ou perguntar).
4. Re-verifique cada pergunta restante contra as fontes antes de enviá-la (Re-verificar antes de perguntar). Uma pergunta que as fontes já respondem custa ao usuário uma decisão que ele nunca precisou tomar.
5. Pergunte a fronteira como uma rodada. A fronteira é toda decisão em aberto cujos pré-requisitos já estão resolvidos: as perguntas que você pode fazer agora sem adivinhar uma resposta que ainda não ouviu. Uma pergunta que depende de outra pergunta ainda em aberto nesta rodada pertence a uma rodada posterior.
6. Apresente cada pergunta com seu briefing. O briefing termina com sua recomendação, para que o usuário decida em um clique com os fatos à vista, sem ler o código primeiro ou compor um design do zero.
7. Recompute a fronteira após cada rodada: decisões resolvidas a expandem, desbloqueiam perguntas que dependiam delas e, frequentemente, aposentam perguntas ou as tornam claras o suficiente para serem resolvidas a partir das evidências. Re-verifique e pergunte na próxima rodada.
8. Pare quando a fronteira estiver vazia: todos os ramos visitados, nada sobrou silenciosamente assumido. Escreva o registro de decisão e deixe o usuário confirmá-lo.

Resolver ou perguntar

A tarefa (ou o plano ou especificação sendo entrevistado) é a ordem e tem precedência: o que ela afirma claramente é implementado como escrito, tão exatamente quanto possível. As tarefas são frequentemente imprecisas, se contradizem ou esquecem coisas, e esses são os pontos que são decididos. Quanto menos decisões o usuário tiver que tomar, melhor, e cada uma pouco clara é dele. O briefing de decisão traça a linha: escreva-o para cada decisão em aberto antes que alguém seja perguntado, e deixe seu resultado colocar o ponto em um dos três casos.

1. A tarefa responde claramente: implemente como escrito. O ponto está resolvido e marcado [Tarefa <ID>], também onde um recurso vizinho o faz de forma diferente ou você teria escolhido de outra forma. Ninguém é perguntado.

2. A tarefa é imprecisa, se contradiz ou omite uma consequência: o usuário decide. Pergunte com o briefing quando sua redação admite duas interpretações ou deixa em aberto o que "pronto" significa; quando descrição, comentários, critérios de aceitação e design discordam; quando sua imagem do código atual não é o que o código mostra; ou quando segui-la literalmente quebraria algo que ela não menciona (comportamento do qual outros recursos dependem, segurança, dados existentes). O que a tarefa significa é uma decisão do usuário, então esses vão para ele mesmo quando você pender para um lado.

3. A tarefa não diz nada: resolva a lacuna quando a evidência for inequívoca, pergunte caso contrário. Resolva você mesmo quando exatamente uma opção se sustenta:

• outra fonte afirma a resposta (um documento vinculado, o design, os documentos do projeto), ou o código trata este caso exato de uma maneira estabelecida (caminho:linha),
• nada nas fontes ou no código aponta para o outro lado,
• nenhuma outra opção tem uma vantagem que alguém poderia razoavelmente classificar como superior, e
• não tem consequências duradouras (modelo de dados, migração, permissão padrão, um contrato que outro módulo ou equipe consome). Esses vão para o usuário sempre que a tarefa estiver em silêncio, por mais confiante que seu próprio raciocínio esteja.

Registre uma lacuna resolvida como uma Annahme com sua evidência em uma linha Beleg: (Registro de decisão); o usuário a vê ao confirmar o registro e pode revertê-la ali. Qualquer outra lacuna vai para o usuário com o briefing, e também todo ponto sobre o qual você não tem certeza: dúvida sobre se um ponto é claro significa que não é.

Re-verificar antes de perguntar

Uma pergunta que chega ao usuário pede a ele que decida, então, antes de uma rodada ser enviada, volte às fontes com as perguntas da rodada em mente. A primeira leitura procurou pelos requisitos; esta procura pela resposta a uma pergunta específica e encontra o que uma leitura geral ignora: uma resposta no fundo de um tópico de comentários, um segundo quadro no design, um critério de aceitação que só funciona de uma maneira.

1. Leia a tarefa novamente por completo, com as perguntas da rodada em mente: descrição, critérios de aceitação, todos os comentários e respostas (não apenas os mais recentes) e as imagens neles.
2. Pesquise as outras fontes pelos termos de cada pergunta, em alemão e inglês e com sinônimos (a entidade, campo, função, tela ou estado sobre o qual se trata): tarefas pai, subtarefas e vinculadas, documentos anexados, comentários de decisões anteriores e documentos de perguntas, todos os quadros e estados do design, os fluxos, os documentos do projeto.
3. Procure uma resposta que decorra do que já está fixo: outro critério de aceitação que funciona com apenas uma opção, uma decisão tomada anteriormente nesta entrevista, um teste ou validação que já fixa um comportamento que a tarefa deixa inalterado.

Em seguida, classifique cada pergunta novamente conforme Resolver ou perguntar: uma resposta que a tarefa afirma claramente a resolve como escrita; uma resposta em outra fonte pode resolver uma lacuna, com seu Beleg:; uma contradição que a re-verificação revelou continua sendo uma pergunta, agora com ambas as citações. Apenas uma pergunta que sobrevive vai para a rodada, e a parte 3 de seu briefing nomeia o que a re-verificação cobriu, para que o usuário veja que a pergunta é real.

Briefing de decisão

Cinco partes nesta ordem, cada uma respondida a partir de evidências que você reuniu nesta sessão: o código como está no branch, as fontes como elas se leem hoje.

1. Ist-Stand im Code (Estado atual no código): o que o código faz hoje onde a decisão recai, com caminho:linha. Para algo que ainda não existe, diga isso e nomeie onde você procurou. Onde a tarefa descreve o comportamento atual de forma diferente do que o código mostra, apresente ambos: essa lacuna é frequentemente a verdadeira questão.
2. Geplante Änderung (Mudança planejada): o que é alterado, adicionado ou removido, como e por quê (o critério de aceitação ou fonte que o exige). Separe o que já está fixo do ponto de bifurcação que as opções resolvem.
3. Ticket und Quellen (Tarefa e fontes): o que a tarefa, seus comentários, tarefas e documentos vinculados, o design e os documentos do projeto dizem sobre este ponto, a tarefa primeiro, citado textualmente em „…“ com a fonte entre parênteses (tarefa e seção, data do comentário, título do documento, nó Figma, CLAUDE.md:<linha>). Cite a frase que importa, não o parágrafo. Onde as fontes discordam, cite cada lado. Quando nenhuma fonte aborda o ponto, diga isso e liste o que a re-verificação cobriu: esse silêncio é o motivo pelo qual é uma pergunta.
4. Optionen (Opções): duas a quatro, as mesmas que a pergunta oferece, cada uma com o que significa concretamente, sua vantagem, sua desvantagem e seu impacto: arquivos e módulos tocados, dados existentes, outras funções ou consumidores, testes, esforço e se é difícil de desfazer depois. Uma opção que o framework já oferece é uma delas.
5. Empfehlung (Recomendação): a opção que você escolheria e por quê, argumentada a partir das partes 1 a 3.

Mantenha cada parte em uma a três linhas: o briefing é o contexto para uma decisão, não um relatório. Escrevê-lo também é o teste de Resolver ou perguntar: quando a parte 3 encontra uma citação que responde ao ponto, ou a parte 1 mostra que o código já o decide, o ponto está resolvido e sai da rodada.

**F1 Comportamento de exclusão de faturas**

1. **Ist-Stand im Code:** `InvoiceService.delete()` exclui fisicamente via `deleteOne` (`projects/api/src/server/modules/invoice/invoice.service.ts:88`), mas não é chamado em lugar nenhum ainda. `Payment.invoice` referencia a fatura (`payment.model.ts:31`). No projeto, existem ambos os padrões: `Order` exclui logicamente via `deletedAt` (`order.service.ts:54`), `Customer` fisicamente (`customer.service.ts:71`).
2. **Geplante Änderung:** Administradores recebem uma ação de exclusão na lista de faturas (CA 3): novo endpoint `DELETE /invoices/:id`, botão em `InvoiceList.vue`. Está fixo quem pode excluir; está em aberto se o registro desaparece.
3. **Ticket und Quellen:**
   - "Administradores devem poder excluir faturas incorretas." (DEV-1234, descrição)
   - "Exclusão apenas para administradores." (DEV-1234, comentário de 02.10.2026)
   - Se as faturas excluídas são mantidas, as fontes não dizem (verificado: descrição, 3 comentários, nó Figma 12:345, `docs/`).
4. **Optionen:**
   - **A Exclusão Lógica** via `deletedAt`, como em `Order`. Vantagem: histórico e referências de `Payment` permanecem válidos. Desvantagem: toda consulta precisa do filtro. Impacto: modelo, serviço e três consultas de lista mudam; nenhuma migração, o campo é opcional.
   - **B Exclusão Física**, como em `Customer`. Vantagem: nenhum campo extra, nenhum filtro. Desvantagem: a fatura desaparece permanentemente. Impacto: referências de `Payment` ficam inválidas e precisam de tratamento próprio.
5. **Empfehlung:** A, porque pagamentos referenciam a fatura e uma fatura excluída não seria mais rastreável.

A tarefa está em silêncio, o projeto tem ambos os precedentes e a escolha molda o modelo de dados, então esta lacuna vai para o usuário. Se a descrição tivesse dito "Faturas excluídas permanecem salvas e são apenas ocultadas", a tarefa teria resolvido: Exclusão Lógica, implementada como escrita, marcada [Tarefa DEV-1234], nenhuma pergunta. Se um comentário tivesse exigido o oposto, a contradição teria ido para o usuário, com ambas as citações na parte 3.

Formato da rodada

Use AskUserQuestion: uma chamada por rodada, até quatro perguntas, cada uma com sua opção recomendada primeiro e sufixo (Recomendada), a descrição de cada opção carregando seu impacto em uma linha. A entrada "Outro" fornecida automaticamente contém respostas de texto livre. Quando a fronteira tiver mais de quatro perguntas, pergunte as mais a montante primeiro; suas respostas geralmente aposentam algumas das restantes.

Coloque os briefings da rodada na mesma mensagem que a chamada, logo antes dela, numerados para corresponder (F1, F2, …), para que o usuário os leia com as perguntas abertas.

Uma pergunta que apenas coleta um fato que só o usuário possui (o que observou, qual conta usou) ou uma escolha de fluxo de trabalho (executar uma revisão, como fazer merge) não precisa de briefing: seus rótulos de opção carregam o que importa.

Sem AskUserQuestion (chat simples, um runner não interativo), imprima a rodada nesse mesmo formato e aguarde as respostas.

Fatos vs decisões

Encontrar fatos é seu trabalho. Perguntar ao usuário por algo que você poderia ter lido é o que faz uma entrevista parecer um interrogatório, e a resposta que você obtém da memória é menos confiável do que a do repositório.

Pesquise você mesmo	Decida (resolva a partir das evidências ou pergunte)
Quais funções um serviço já permite (@Restricted, @Roles, securityCheck)	Quais funções devem ser permitidas
A forma atual de uma entidade, DTO ou tipo gerado (types.gen.ts, sdk.gen.ts)	Se um campo é adicionado, renomeado ou substituído
Se um endpoint, página ou composable já existe	Se deve estendê-lo ou construir ao lado
O que a tarefa, seus comentários e o nó Figma vinculado realmente dizem	O que a tarefa significa onde é ambígua
Como um recurso vizinho resolveu o mesmo problema	Se este recurso deve seguir esse precedente
Quais testes cobrem os caminhos afetados hoje	Em quais costuras os novos testes devem se sentar
Se o defeito descrito ainda se reproduz	Qual é o comportamento correto em vez disso

Use Read, Grep, Glob, o Linear MCP e o Figma MCP antes de fazer uma pergunta. Onde uma pesquisa é ampla, despache um subagente para ela e não bloqueie: uma pesquisa em andamento é um pré-requisito não resolvido, então apenas as perguntas a jusante dela esperam, e o resto da fronteira é perguntado agora.

Qualidade da pergunta

• Explore os limites, não o caminho feliz. Vazio, nulo, muito grande, concorrente, não autorizado, offline. O caminho feliz é a parte com a qual todos já concordam.
• Superficie as consequências que sobrevivem à tarefa: um modelo de dados difícil de migrar depois, uma permissão padrão que se torna o precedente, um contrato que outras equipes consumirão.
• Um novo projeto nest-server resolve seu banco de dados nesta rodada. A menos que a tarefa ou uma seção ## Database no CLAUDE.md raiz o nomeie, o banco de dados e o mecanismo SQL são uma pergunta (eles sobrevivem a toda tarefa), informada pelo procedimento em generating-nest-servers → reference/choosing-a-database.md: o sinal das fontes na parte 3, a etapa de decisão na parte 5, e para MySQL/MariaDB o que o projeto abre mão. Um novo módulo com seus próprios dados permanece no banco de dados do projeto sem questionamento; torna-se uma pergunta apenas quando as fontes apontam para outro banco de dados (híbrido). A resposta confirmada vai para o registro de decisão e, como ## Database, para o CLAUDE.md raiz.
• Cubra onde a implementação, de outra forma, pararia. Antes de fechar, percorra o trabalho planejado uma vez em sua mente (modelos, endpoints, permissões, estados de UI, testes) e coloque cada ponto onde você, de outra forma, pausaria através de Resolver ou perguntar. Isso é o que torna a execução posterior livre de perguntas.

Quando o usuário está inacessível

Uma decisão pouco clara pertence ao usuário, então uma decisão bloqueadora nunca é respondida em seu nome

...

[truncado para tradução]