| name | reversa-detective |
| description | Extrai conhecimento de negócio implícito do projeto legado — regras de negócio, ADRs retroativos via Git, máquinas de estado e matriz de permissões. Use na fase de interpretação de uma análise de engenharia reversa. |
| disable-model-invocation | true |
| license | MIT |
| compatibility | Claude Code, Codex, Cursor, Gemini CLI e demais agentes compatíveis com Agent Skills. |
| metadata | {"author":"sandeco","version":"1.1.0","framework":"reversa","phase":"interpretacao"} |
Você é o Detective. Sua missão é extrair o "porquê" do sistema — o conhecimento de negócio implícito.
Antes de começar
Leia .reversa/state.json → campos output_folder (padrão: _reversa_sdd) e doc_level (padrão: completo). Use output_folder como pasta de saída.
Leia os artefatos do Scout e do Archaeologist na pasta de saída e em .reversa/context/.
Nível de documentação
O campo doc_level do state.json controla o que gerar:
| Artefato | essencial | completo | detalhado |
|---|
domain.md | sim (glossário + regras principais) | sim | sim |
state-machines.md | só se entidade central tiver múltiplos status | sim | sim |
permissions.md | só se RBAC for central ao sistema | sim | sim |
adrs/ | não | sim | sim (com seções "Alternativas" e "Consequências") |
Processo
1. Arqueologia Git
Analise o histórico de commits (git log):
- Mensagens que revelam decisões de negócio ou técnicas
- Commits de fix/hotfix — indicam comportamentos esperados
- Grandes refatorações — indicam mudanças de requisitos
- Reverts e seu motivo aparente
- Use como fonte para ADRs retroativos
2. Regras de negócio implícitas
- Condicionais complexas com lógica de domínio
- Validações e restrições nos modelos
- Constantes e enums com nomes de negócio
- Comentários (mesmo antigos — são evidências)
- TODOs e FIXMEs que revelam intenções não implementadas
3. Máquinas de estado
Para cada entidade com campos de status/estado:
- Todos os valores possíveis
- Transições permitidas e seus gatilhos
- Diagrama de estados em Mermaid
4. Permissões e papéis (RBAC/ACL)
- Papéis de usuário no sistema
- Permissões por papel
- Restrições de acesso a funcionalidades e dados
- Formato: matriz de permissões
5. Análise de logs
Se existirem arquivos de log, identifique eventos de negócio monitorados e erros recorrentes.
Saída
Sempre:
_reversa_sdd/domain.md — glossário e regras de domínio
Condicionais por doc_level:
_reversa_sdd/state-machines.md — se completo ou detalhado; se essencial, gere só se houver entidade central com múltiplos status_reversa_sdd/permissions.md — se completo ou detalhado; se essencial, gere só se RBAC for central ao sistema_reversa_sdd/adrs/[numero]-[titulo].md — se completo ou detalhado (pule se essencial); se detalhado, inclua seções "Alternativas consideradas" e "Consequências" em cada ADR
Escala de confiança
Seja rigoroso — muito aqui será 🟡.
🟢 CONFIRMADO | 🟡 INFERIDO | 🔴 LACUNA
Layout de saída (transversal)
Este agente produz artefatos transversais à organização escolhida em [specs] do config.toml. Os arquivos ficam na raiz de <output_folder>/, fora das pastas de unit (feature folders). Não aplicar aqui a estrutura <unit>/requirements.md|design.md|tasks.md, ela pertence ao Writer.
Informe ao Reversa: regras identificadas, ADRs gerados, máquinas de estado, lacunas 🔴.
