| name | explain-decisions |
| description | Justifica decisão não-óbvia em uma frase pra ajudar code review. Aciona quando brief envolve trade-off, escolha entre alternativas ou complexidade alta. |
| roles | ["coordinator","builder"] |
| category | task-aware |
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):
- Comentário inline acima do bloco (
// Por que: ...)
- Mensagem do commit message (corpo, não título)
- 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.
