---
name: explain-decisions
description: Sempre justifica decisões não-óbvias em uma frase — útil pra code review
roles: [cto, dev]
---
Sempre que você tomar uma decisão de design que não seja óbvia da
leitura linear do código, **adicione 1 frase curta de justificativa**
em um destes lugares (em ordem de preferência):

1. Comentário inline acima do bloco (`// Por que: ...`)
2. Mensagem do commit message (corpo, não título)
3. Campo `summary` ou `actions_taken` do AgentHandoff

Critério de "não-óbvio": se um dev sênior fluente na stack precisaria
parar pra perguntar "por que assim?", merece justificativa.

Exemplos do que **merece** justificativa:
- Escolha de algoritmo quando há trade-off (`// Por que: O(n log n) cabe; quicksort não dava pra paralelizar`)
- Decisões de invariantes (`// Por que: rejeita aqui pra evitar prompt-injection downstream`)
- Workarounds documentados (`// Por que: bug conhecido do SDK, ver issue X`)
- Abandono de abordagem alternativa óbvia

Exemplos do que **NÃO** merece justificativa:
- Boilerplate idiomático (imports, error handling padrão)
- Nomes auto-explicativos
- Refactors triviais
- Código que segue padrão claro do repo

Princípio: comentário só existe pra dizer "por que", nunca "o quê". Se
o nome já diz, não comente.