Use o /dr:debug quando algo não está funcionando e você quer entender o porquê antes de mexer. Um bug, um build quebrado, uma tela lenta, um erro de deploy, um defeito visual: você descreve o problema, o comando investiga e volta com um diagnóstico e as correções propostas. Só depois da sua escolha ele toca no código.
O problema, com suas palavras: o que deveria acontecer, o que acontece e, se tiver, a mensagem de erro. Pode colar o erro inteiro. Se souber a natureza do problema (bug, build, performance, deploy, interface), vale indicar, mas não é obrigatório: o comando descobre pelo contexto.
A investigação é só leitura. O comando parte da sua descrição, levanta o contexto do código, dos logs e do ambiente, lista as causas prováveis e vai eliminando hipóteses até chegar à causa raiz. Para problemas de interface, quando a análise estática não basta, ele abre o navegador, reproduz o problema e captura telas e console como evidência.
Ao final, ele apresenta o que encontrou e as correções que propõe, separadas em dois grupos: a correção recomendada, que ataca a causa raiz, e as melhorias relacionadas, que ele viu no caminho. Então pergunta o que você quer aplicar: só a recomendada, todas, ou nenhuma, ficando apenas com o relatório.
O diagnóstico documentado e, se você escolheu aplicar, as correções feitas, limitadas ao que foi selecionado e respeitando o estilo e os padrões do código. Depois de corrigir, o comando roda o lint e o typecheck do projeto e relata o resultado como ele é, confrontando a correção com o problema que você relatou. Se a investigação concluir que não há o que corrigir, ele encerra no relatório.
Na prática, aquela hora de “onde é que isso está quebrando” vira um relatório com a causa, as opções e a decisão nas suas mãos.
Exemplos
/dr:debug o login redireciona para 404 depois do OAuth
/dr:debug build falha com "Cannot find module" --type build
/dr:debug a listagem de pedidos demora 8 segundos --type performance
/dr:debug o modal não fecha no Safari --type ui --playwright
Argumentos
| Argumento | Obrigatório? | Descrição |
|---|
issue | Sim | Description of the problem or error message |
--type | Não | Issue category (bug, build, performance, deployment, ui, documentation) |
--trace | Não | Enable detailed tracing and logging |
--yes | Não | Skip the fix confirmation and automatically apply the recommended fix (for non-interactive/headless usage). The legacy `--fix` flag is accepted as an alias of `--yes` (fixing is now the default behavior; these flags only skip the confirmation). |
Notas
--type aceita bug, build, performance, deployment, ui e documentation. --trace ativa rastreamento detalhado e --verify-docs compara a implementação com a documentação dos componentes afetados. Use --yes para aplicar a correção recomendada sem a pergunta de confirmação (uso não interativo); o legado --fix é aceito como sinônimo de --yes.
Para quem quer saber o que acontece nos bastidores:
- Registro: cada investigação ganha a pasta
.dr_ai/tasks/debug-<timestamp>/ com o __DebugSummary.md, que começa com o problema relatado e termina com a análise, a causa raiz e a seção de correções aplicadas ou recusadas.
- Interface: a reprodução no navegador usa o Playwright, só quando o problema é visual ou de interação e a análise do código não basta; a flag
--playwright força esse caminho.
- Documentação: com
--verify-docs, o comando compara a implementação com a documentação dos componentes afetados e registra as divergências no resumo.
- Validação: as correções são aplicadas com edições pontuais, seguidas do lint e do typecheck do projeto quando existirem.
- /dr:implement — quando o trabalho é construir algo novo ou alterar código existente, não investigar
- /dr:talk:explain — entender um trecho de código antes de mexer nele
