Refactor Analista Processual Squad: 3-tier architecture with 7 specialized agents#5
Merged
felippepestana merged 1 commit intomainfrom Mar 30, 2026
Merged
Conversation
Guia do RevisorRefatora a squad Analista Processual de um fluxo linear simples de 3 agentes para uma arquitetura orquestrada em 3 camadas, com 7 agentes especializados, modos duplos processual/jurídico, gates de qualidade explícitos, uso mais rico de ferramentas e um ponto de entrada compatível com CLI para execução. Diagrama de sequência para o fluxo completo de análise judicial UC-AP-002sequenceDiagram
actor User
participant Orchestrator
participant LeitorDePecas
participant PesquisadorJuridico
participant EstrategistaProcessual
participant AdvogadoOrientador
participant DocumentadorProcessual
participant FileSystem
User->>Orchestrator: Envia descrição do caso judicial
Orchestrator->>Orchestrator: QG-AP-001 classifica como UC-AP-002
par Extração_de_peças
Orchestrator->>LeitorDePecas: Ativa leitor_de_pecas com documentos
LeitorDePecas->>LeitorDePecas: Usa Read/Glob/Grep para extrair 7 categorias
LeitorDePecas-->>Orchestrator: Tabelas estruturadas por documento
and Pesquisa_jurisprudencial
Orchestrator->>PesquisadorJuridico: Ativa pesquisador_juridico com tese jurídica
PesquisadorJuridico->>PesquisadorJuridico: Usa WebSearch/Read/Grep
PesquisadorJuridico-->>Orchestrator: Mínimo 5 fontes com citações formais
end
Orchestrator->>EstrategistaProcessual: Envia extrações + jurisprudência
EstrategistaProcessual->>EstrategistaProcessual: Analisa riscos e cenários (3) com % = 100
EstrategistaProcessual-->>Orchestrator: Relatório estratégico com cenários
Orchestrator->>AdvogadoOrientador: Envia análise estratégica
AdvogadoOrientador->>AdvogadoOrientador: Gera plano de ação e orientação ao cliente
AdvogadoOrientador-->>Orchestrator: Plano com ações 7 dias e 4-8 semanas
Orchestrator->>DocumentadorProcessual: Consolida outputs (modo jurídico)
DocumentadorProcessual->>DocumentadorProcessual: Detecta MODO_JURIDICO (uso do leitor_de_pecas)
DocumentadorProcessual->>DocumentadorProcessual: Monta relatório Markdown + bloco citacoes
DocumentadorProcessual->>FileSystem: Write relatorio-[processo-slug]-[AAAA-MM-DD].md
FileSystem-->>DocumentadorProcessual: Caminho confirmado
DocumentadorProcessual-->>Orchestrator: Confirmação QG-AP-004 + resumo
Orchestrator-->>User: Indica local do arquivo e apresenta resumo executivo
Diagrama de classes para o orquestrador e agentes especializadosclassDiagram
class AnalistaProcessualSquad {
+run_squad(input_text)
+main()
-SYSTEM_PROMPT
-agents
-allowed_tools
}
class AgentDefinition {
+description
+prompt
+tools
}
class MapeadorProcessual {
+description
+prompt
+tools : [Read, Glob]
}
class AvaliadorProcessual {
+description
+prompt
+tools : [Read]
}
class LeitorDePecas {
+description
+prompt
+tools : [Read, Glob, Grep]
}
class PesquisadorJuridico {
+description
+prompt
+tools : [Read, Glob, Grep, WebSearch]
}
class EstrategistaProcessual {
+description
+prompt
+tools : [Read, Grep]
}
class AdvogadoOrientador {
+description
+prompt
+tools : [Read]
}
class DocumentadorProcessual {
+description
+prompt
+tools : [Read, Write, Grep, Glob]
+modo
}
AnalistaProcessualSquad --> AgentDefinition : utiliza
AgentDefinition <|-- MapeadorProcessual
AgentDefinition <|-- AvaliadorProcessual
AgentDefinition <|-- LeitorDePecas
AgentDefinition <|-- PesquisadorJuridico
AgentDefinition <|-- EstrategistaProcessual
AgentDefinition <|-- AdvogadoOrientador
AgentDefinition <|-- DocumentadorProcessual
Diagrama de estados para o comportamento em modo duplo do Documentador ProcessualstateDiagram-v2
[*] --> AguardandoContexto
state AguardandoContexto {
[*] --> SemModoDefinido
SemModoDefinido --> ModoProcessual : Apenas mapeador_processual
SemModoDefinido --> ModoJuridico : Inclui leitor_de_pecas
}
state ModoProcessual {
[*] --> MontandoRelatorioProcessual
MontandoRelatorioProcessual --> SalvandoArquivoProcessual : Write relatorio-[processo-slug]-[AAAA-MM-DD].md
SalvandoArquivoProcessual --> QG_AP_004_Processual : Confirma uso de Write
QG_AP_004_Processual --> [*]
}
state ModoJuridico {
[*] --> MontandoRelatorioJuridico
MontandoRelatorioJuridico --> AdicionandoBlocoCitacoes : Anexa bloco citacoes
AdicionandoBlocoCitacoes --> SalvandoArquivoJuridico : Write relatorio-[processo-slug]-[AAAA-MM-DD].md
SalvandoArquivoJuridico --> QG_AP_004_Juridico : Confirma uso de Write
QG_AP_004_Juridico --> [*]
}
Alterações em nível de arquivo
Dicas e comandosInteragindo com o Sourcery
Personalizando sua experiênciaAcesse seu dashboard para:
Obtendo ajuda
Original review guide in EnglishReviewer's GuideRefactors the Analista Processual squad from a simple 3-agent linear flow into a 3‑tier orchestrated architecture with 7 specialized agents, dual process/judicial modes, explicit quality gates, richer tool usage, and a CLI-friendly runner entrypoint. Sequence diagram for UC-AP-002 full judicial analysis flowsequenceDiagram
actor User
participant Orchestrator
participant LeitorDePecas
participant PesquisadorJuridico
participant EstrategistaProcessual
participant AdvogadoOrientador
participant DocumentadorProcessual
participant FileSystem
User->>Orchestrator: Envia descrição do caso judicial
Orchestrator->>Orchestrator: QG-AP-001 classifica como UC-AP-002
par Extração_de_peças
Orchestrator->>LeitorDePecas: Ativa leitor_de_pecas com documentos
LeitorDePecas->>LeitorDePecas: Usa Read/Glob/Grep para extrair 7 categorias
LeitorDePecas-->>Orchestrator: Tabelas estruturadas por documento
and Pesquisa_jurisprudencial
Orchestrator->>PesquisadorJuridico: Ativa pesquisador_juridico com tese jurídica
PesquisadorJuridico->>PesquisadorJuridico: Usa WebSearch/Read/Grep
PesquisadorJuridico-->>Orchestrator: Mínimo 5 fontes com citações formais
end
Orchestrator->>EstrategistaProcessual: Envia extrações + jurisprudência
EstrategistaProcessual->>EstrategistaProcessual: Analisa riscos e cenários (3) com % = 100
EstrategistaProcessual-->>Orchestrator: Relatório estratégico com cenários
Orchestrator->>AdvogadoOrientador: Envia análise estratégica
AdvogadoOrientador->>AdvogadoOrientador: Gera plano de ação e orientação ao cliente
AdvogadoOrientador-->>Orchestrator: Plano com ações 7 dias e 4-8 semanas
Orchestrator->>DocumentadorProcessual: Consolida outputs (modo jurídico)
DocumentadorProcessual->>DocumentadorProcessual: Detecta MODO_JURIDICO (uso do leitor_de_pecas)
DocumentadorProcessual->>DocumentadorProcessual: Monta relatório Markdown + bloco citacoes
DocumentadorProcessual->>FileSystem: Write relatorio-[processo-slug]-[AAAA-MM-DD].md
FileSystem-->>DocumentadorProcessual: Caminho confirmado
DocumentadorProcessual-->>Orchestrator: Confirmação QG-AP-004 + resumo
Orchestrator-->>User: Indica local do arquivo e apresenta resumo executivo
Class diagram for orchestrator and specialized agentsclassDiagram
class AnalistaProcessualSquad {
+run_squad(input_text)
+main()
-SYSTEM_PROMPT
-agents
-allowed_tools
}
class AgentDefinition {
+description
+prompt
+tools
}
class MapeadorProcessual {
+description
+prompt
+tools : [Read, Glob]
}
class AvaliadorProcessual {
+description
+prompt
+tools : [Read]
}
class LeitorDePecas {
+description
+prompt
+tools : [Read, Glob, Grep]
}
class PesquisadorJuridico {
+description
+prompt
+tools : [Read, Glob, Grep, WebSearch]
}
class EstrategistaProcessual {
+description
+prompt
+tools : [Read, Grep]
}
class AdvogadoOrientador {
+description
+prompt
+tools : [Read]
}
class DocumentadorProcessual {
+description
+prompt
+tools : [Read, Write, Grep, Glob]
+modo
}
AnalistaProcessualSquad --> AgentDefinition : utiliza
AgentDefinition <|-- MapeadorProcessual
AgentDefinition <|-- AvaliadorProcessual
AgentDefinition <|-- LeitorDePecas
AgentDefinition <|-- PesquisadorJuridico
AgentDefinition <|-- EstrategistaProcessual
AgentDefinition <|-- AdvogadoOrientador
AgentDefinition <|-- DocumentadorProcessual
State diagram for Documentador Processual dual-mode behaviorstateDiagram-v2
[*] --> AguardandoContexto
state AguardandoContexto {
[*] --> SemModoDefinido
SemModoDefinido --> ModoProcessual : Apenas mapeador_processual
SemModoDefinido --> ModoJuridico : Inclui leitor_de_pecas
}
state ModoProcessual {
[*] --> MontandoRelatorioProcessual
MontandoRelatorioProcessual --> SalvandoArquivoProcessual : Write relatorio-[processo-slug]-[AAAA-MM-DD].md
SalvandoArquivoProcessual --> QG_AP_004_Processual : Confirma uso de Write
QG_AP_004_Processual --> [*]
}
state ModoJuridico {
[*] --> MontandoRelatorioJuridico
MontandoRelatorioJuridico --> AdicionandoBlocoCitacoes : Anexa bloco citacoes
AdicionandoBlocoCitacoes --> SalvandoArquivoJuridico : Write relatorio-[processo-slug]-[AAAA-MM-DD].md
SalvandoArquivoJuridico --> QG_AP_004_Juridico : Confirma uso de Write
QG_AP_004_Juridico --> [*]
}
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey - encontrei 3 problemas e deixei alguns comentários em alto nível:
- A constante do agente
mapeador-processualestá nomeada de forma inconsistente (MAEADOR_PROCESSUALvsMAEDADOR_PROCESSUALvsmapeador-processual), o que vai gerar um NameError em tempo de execução; alinhe o nome da constante e o seu uso no dicionárioagents. - Dado os QUALITY GATES mais rigorosos descritos no system prompt (especialmente o QG-AP-004 sobre o uso de Write), considere adicionar uma pequena verificação programática em torno do
ResultMessagefinal ou da camada de tooling para validar que odocumentador-processualde fato invocou o Write, em vez de depender apenas das instruções de prompt.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- A constante do agente `mapeador-processual` está nomeada de forma inconsistente (`MAEADOR_PROCESSUAL` vs `MAEDADOR_PROCESSUAL` vs `mapeador-processual`), o que vai gerar um NameError em tempo de execução; alinhe o nome da constante e o seu uso no dicionário `agents`.
- Dado os QUALITY GATES mais rigorosos descritos no system prompt (especialmente o QG-AP-004 sobre o uso de Write), considere adicionar uma pequena verificação programática em torno do `ResultMessage` final ou da camada de tooling para validar que o `documentador-processual` de fato invocou o Write, em vez de depender apenas das instruções de prompt.
## Individual Comments
### Comment 1
<location path="squads/analista-processual/squad.py" line_range="32-41" />
<code_context>
+MAEADOR_PROCESSUAL = AgentDefinition(
</code_context>
<issue_to_address>
**issue (bug_risk):** A nomenclatura inconsistente do agente mapeador vai causar um NameError em tempo de execução.
O agente é definido como `MAEADOR_PROCESSUAL`, mas o mapeamento `agents` utiliza `MAEDADOR_PROCESSUAL`, então o módulo vai levantar um NameError ao construir o dicionário. Por favor, escolha um nome único, consistente e correto (por exemplo, `MAPEADOR_PROCESSUAL`) tanto para a constante quanto para a sua entrada em `agents`.
</issue_to_address>
### Comment 2
<location path="squads/analista-processual/squad.py" line_range="164" />
<code_context>
+ "2. ANÁLISE DE RISCOS E OPORTUNIDADES:\n"
+ " - Riscos jurídicos (prescrição, preclusão, nulidades)\n"
+ " - Oportunidades processuais (tutelas, reconvenção, etc.)\n\n"
+ "3. CENAÁRIOS (3 obrigatórios com %):\n"
+ " - Otimista: [descrição] — Probabilidade: X%\n"
+ " - Realista: [descrição] — Probabilidade: X%\n"
</code_context>
<issue_to_address>
**nitpick (typo):** Erro de digitação na palavra “CENAÁRIOS” dentro do prompt do estrategista.
Como este é um texto de prompt exibido ao usuário, corrija a grafia para `CENÁRIOS` para manter a orientação clara e bem acabada.
```suggestion
"3. CENÁRIOS (3 obrigatórios com %):\n"
```
</issue_to_address>
### Comment 3
<location path="squads/analista-processual/squad.py" line_range="127-129" />
<code_context>
+ prompt=(
+ "Você é um pesquisador jurídico especializado em jurisprudência brasileira.\n\n"
+ "FONTES AUTORIZADAS:\n"
+ "- stf.jus.br (controle constitucional, reperucussão geral)\n"
+ "- stj.jus.br (recurso especial, súmulas, teses repetitivas)\n"
+ "- tst.jus.br (matéria trabalhista)\n"
</code_context>
<issue_to_address>
**nitpick (typo):** Pequeno erro de grafia em “reperucussão geral” dentro do prompt do pesquisador.
A grafia correta é `repercussão geral`. Atualizar isso deixa o prompt mais claro e evita que o termo incorreto seja reutilizado.
```suggestion
"FONTES AUTORIZADAS:\n"
"- stf.jus.br (controle constitucional, repercussão geral)\n"
"- stj.jus.br (recurso especial, súmulas, teses repetitivas)\n"
```
</issue_to_address>Sourcery is free for open source - if you like our reviews please consider sharing them ✨
Original comment in English
Hey - I've found 3 issues, and left some high level feedback:
- The
mapeador-processualagent constant is inconsistently named (MAEADOR_PROCESSUALvsMAEDADOR_PROCESSUALvsmapeador-processual), which will raise a NameError at runtime; align the constant name and its usage in theagentsdict. - Given the stricter QUALITY GATES described in the system prompt (especially QG-AP-004 around Write usage), consider adding a small programmatic check around the final
ResultMessageor tooling layer to validate thatdocumentador-processualactually invoked Write rather than relying solely on prompt instructions.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- The `mapeador-processual` agent constant is inconsistently named (`MAEADOR_PROCESSUAL` vs `MAEDADOR_PROCESSUAL` vs `mapeador-processual`), which will raise a NameError at runtime; align the constant name and its usage in the `agents` dict.
- Given the stricter QUALITY GATES described in the system prompt (especially QG-AP-004 around Write usage), consider adding a small programmatic check around the final `ResultMessage` or tooling layer to validate that `documentador-processual` actually invoked Write rather than relying solely on prompt instructions.
## Individual Comments
### Comment 1
<location path="squads/analista-processual/squad.py" line_range="32-41" />
<code_context>
+MAEADOR_PROCESSUAL = AgentDefinition(
</code_context>
<issue_to_address>
**issue (bug_risk):** Inconsistent naming of the mapeador agent will cause a NameError at runtime.
The agent is defined as `MAEADOR_PROCESSUAL`, but the `agents` mapping uses `MAEDADOR_PROCESSUAL`, so the module will raise a NameError when building the dict. Please choose one consistent, correct name (e.g. `MAPEADOR_PROCESSUAL`) for both the constant and its entry in `agents`.
</issue_to_address>
### Comment 2
<location path="squads/analista-processual/squad.py" line_range="164" />
<code_context>
+ "2. ANÁLISE DE RISCOS E OPORTUNIDADES:\n"
+ " - Riscos jurídicos (prescrição, preclusão, nulidades)\n"
+ " - Oportunidades processuais (tutelas, reconvenção, etc.)\n\n"
+ "3. CENAÁRIOS (3 obrigatórios com %):\n"
+ " - Otimista: [descrição] — Probabilidade: X%\n"
+ " - Realista: [descrição] — Probabilidade: X%\n"
</code_context>
<issue_to_address>
**nitpick (typo):** Typo in the word “CENAÁRIOS” inside the strategist prompt.
Since this is user-facing prompt text, please correct the spelling to `CENÁRIOS` to keep the guidance clear and polished.
```suggestion
"3. CENÁRIOS (3 obrigatórios com %):\n"
```
</issue_to_address>
### Comment 3
<location path="squads/analista-processual/squad.py" line_range="127-129" />
<code_context>
+ prompt=(
+ "Você é um pesquisador jurídico especializado em jurisprudência brasileira.\n\n"
+ "FONTES AUTORIZADAS:\n"
+ "- stf.jus.br (controle constitucional, reperucussão geral)\n"
+ "- stj.jus.br (recurso especial, súmulas, teses repetitivas)\n"
+ "- tst.jus.br (matéria trabalhista)\n"
</code_context>
<issue_to_address>
**nitpick (typo):** Minor spelling error in “reperucussão geral” within the researcher prompt.
It should be spelled `repercussão geral`. Updating this keeps the prompt clear and prevents the incorrect term from being reused.
```suggestion
"FONTES AUTORIZADAS:\n"
"- stf.jus.br (controle constitucional, repercussão geral)\n"
"- stj.jus.br (recurso especial, súmulas, teses repetitivas)\n"
```
</issue_to_address>Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
Comment on lines
+32
to
+41
| MAEADOR_PROCESSUAL = AgentDefinition( | ||
| description=( | ||
| "Especialista em mapeamento de processos. " | ||
| "Identifica todas as etapas, atores, entradas, saídas e decisões " | ||
| "de um processo e os organiza em um fluxo claro e sequencial." | ||
| "Especialista em mapeamento de processos organizacionais e jurídicos. " | ||
| "Recebe a descrição de um processo e produz tabela estruturada com: " | ||
| "etapas em ordem cronológica, ator responsável, entradas (inputs), " | ||
| "saídas (outputs), critério de conclusão e pontos de decisão (gateways). " | ||
| "Não avalia riscos — apenas mapeia o estado atual." | ||
| ), | ||
| prompt=( | ||
| "Você é um analista de processos sênior especializado em mapeamento. " | ||
| "Dado um processo descrito pelo usuário:\n" | ||
| "1. Liste todas as etapas na ordem correta.\n" | ||
| "2. Para cada etapa, indique: ator responsável, entradas necessárias, " | ||
| "saídas produzidas e critérios de conclusão.\n" | ||
| "3. Identifique pontos de decisão (gateways) e ramificações.\n" | ||
| "4. Represente o fluxo em formato textual estruturado (pseudo-BPMN)." | ||
| "Você é um especialista sênior em mapeamento e modelagem de processos." |
There was a problem hiding this comment.
issue (bug_risk): A nomenclatura inconsistente do agente mapeador vai causar um NameError em tempo de execução.
O agente é definido como MAEADOR_PROCESSUAL, mas o mapeamento agents utiliza MAEDADOR_PROCESSUAL, então o módulo vai levantar um NameError ao construir o dicionário. Por favor, escolha um nome único, consistente e correto (por exemplo, MAPEADOR_PROCESSUAL) tanto para a constante quanto para a sua entrada em agents.
Original comment in English
issue (bug_risk): Inconsistent naming of the mapeador agent will cause a NameError at runtime.
The agent is defined as MAEADOR_PROCESSUAL, but the agents mapping uses MAEDADOR_PROCESSUAL, so the module will raise a NameError when building the dict. Please choose one consistent, correct name (e.g. MAPEADOR_PROCESSUAL) for both the constant and its entry in agents.
| "2. ANÁLISE DE RISCOS E OPORTUNIDADES:\n" | ||
| " - Riscos jurídicos (prescrição, preclusão, nulidades)\n" | ||
| " - Oportunidades processuais (tutelas, reconvenção, etc.)\n\n" | ||
| "3. CENAÁRIOS (3 obrigatórios com %):\n" |
There was a problem hiding this comment.
nitpick (typo): Erro de digitação na palavra “CENAÁRIOS” dentro do prompt do estrategista.
Como este é um texto de prompt exibido ao usuário, corrija a grafia para CENÁRIOS para manter a orientação clara e bem acabada.
Suggested change
| "3. CENAÁRIOS (3 obrigatórios com %):\n" | |
| "3. CENÁRIOS (3 obrigatórios com %):\n" |
Original comment in English
nitpick (typo): Typo in the word “CENAÁRIOS” inside the strategist prompt.
Since this is user-facing prompt text, please correct the spelling to CENÁRIOS to keep the guidance clear and polished.
Suggested change
| "3. CENAÁRIOS (3 obrigatórios com %):\n" | |
| "3. CENÁRIOS (3 obrigatórios com %):\n" |
Comment on lines
+127
to
+129
| "FONTES AUTORIZADAS:\n" | ||
| "- stf.jus.br (controle constitucional, reperucussão geral)\n" | ||
| "- stj.jus.br (recurso especial, súmulas, teses repetitivas)\n" |
There was a problem hiding this comment.
nitpick (typo): Pequeno erro de grafia em “reperucussão geral” dentro do prompt do pesquisador.
A grafia correta é repercussão geral. Atualizar isso deixa o prompt mais claro e evita que o termo incorreto seja reutilizado.
Suggested change
| "FONTES AUTORIZADAS:\n" | |
| "- stf.jus.br (controle constitucional, reperucussão geral)\n" | |
| "- stj.jus.br (recurso especial, súmulas, teses repetitivas)\n" | |
| "FONTES AUTORIZADAS:\n" | |
| "- stf.jus.br (controle constitucional, repercussão geral)\n" | |
| "- stj.jus.br (recurso especial, súmulas, teses repetitivas)\n" |
Original comment in English
nitpick (typo): Minor spelling error in “reperucussão geral” within the researcher prompt.
It should be spelled repercussão geral. Updating this keeps the prompt clear and prevents the incorrect term from being reused.
Suggested change
| "FONTES AUTORIZADAS:\n" | |
| "- stf.jus.br (controle constitucional, reperucussão geral)\n" | |
| "- stj.jus.br (recurso especial, súmulas, teses repetitivas)\n" | |
| "FONTES AUTORIZADAS:\n" | |
| "- stf.jus.br (controle constitucional, repercussão geral)\n" | |
| "- stj.jus.br (recurso especial, súmulas, teses repetitivas)\n" |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request refactors the Analista Processual squad into a 3-tier pipeline for Brazilian organizational and legal process analysis. It introduces specialized agents for document extraction, legal research, and strategic planning, governed by a new orchestrator logic. Feedback identifies a critical import error caused by invalid package naming, multiple typos in variable definitions that will lead to runtime failures, and a regression in CLI usability where the interactive prompt was removed.
| @@ -0,0 +1,4 @@ | |||
| """Allow running as: python -m squads.analista-processual""" | |||
| from squads.analista_processual.squad import main | |||
There was a problem hiding this comment.
Esta instrução de importação causará um ImportError em tempo de execução. O caminho squads.analista_processual implica um diretório chamado analista_processual, mas o diretório real no repositório é analista-processual. Nomes de pacotes Python não podem conter hifens. Para que o módulo possa ser executado com python -m, o diretório analista-processual deve ser renomeado para um nome de pacote válido (por exemplo, analista_processual), e esta instrução de importação provavelmente precisará ser ajustada.
| # --------------------------------------------------------------------------- | ||
|
|
||
| MAPEADOR = AgentDefinition( | ||
| MAEADOR_PROCESSUAL = AgentDefinition( |
There was a problem hiding this comment.
Parece haver um erro de digitação no nome desta variável. Com base na função do agente ("mapeador"), o nome pretendido é provavelmente MAPEADOR_PROCESSUAL. Este erro, combinado com outro no seu uso na linha 312, causará um NameError em tempo de execução.
Suggested change
| MAEADOR_PROCESSUAL = AgentDefinition( | |
| MAPEADOR_PROCESSUAL = AgentDefinition( |
| "mapeador": MAPEADOR, | ||
| "avaliador": AVALIADOR, | ||
| "documentador": DOCUMENTADOR, | ||
| "mapeador-processual": MAEDADOR_PROCESSUAL, |
There was a problem hiding this comment.
Esta linha irá gerar um NameError porque a variável MAEDADOR_PROCESSUAL não está definida. Parece ser um erro de digitação da variável definida na linha 32 (MAEADOR_PROCESSUAL), que por sua vez também parece ser um erro de digitação para MAPEADOR_PROCESSUAL. Por favor, corrija tanto a definição na linha 32 quanto o uso aqui.
Suggested change
| "mapeador-processual": MAEDADOR_PROCESSUAL, | |
| "mapeador-processual": MAPEADOR_PROCESSUAL, |
Comment on lines
333
to
+336
| if len(sys.argv) > 1: | ||
| processo = " ".join(sys.argv[1:]) | ||
| elif not sys.stdin.isatty(): | ||
| processo = sys.stdin.read().strip() | ||
| input_text = " ".join(sys.argv[1:]) | ||
| else: | ||
| print("Descreva o processo que deseja analisar (Ctrl+D para finalizar):") | ||
| processo = sys.stdin.read().strip() | ||
| input_text = sys.stdin.read().strip() |
There was a problem hiding this comment.
A implementação anterior lidava com o modo interativo de forma mais elegante, verificando sys.stdin.isatty() e exibindo um prompt. Esta alteração remove essa lógica, fazendo com que o script pareça travar sem nenhuma mensagem quando executado interativamente sem argumentos. Isso é uma regressão na usabilidade. Considere restaurar a verificação de um terminal interativo.
if len(sys.argv) > 1:
input_text = " ".join(sys.argv[1:])
elif not sys.stdin.isatty():
input_text = sys.stdin.read().strip()
else:
print("Descreva o processo que deseja analisar (Ctrl+D para finalizar):", file=sys.stderr)
input_text = sys.stdin.read().strip()![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 4482396688
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| "mapeador": MAPEADOR, | ||
| "avaliador": AVALIADOR, | ||
| "documentador": DOCUMENTADOR, | ||
| "mapeador-processual": MAEDADOR_PROCESSUAL, |
There was a problem hiding this comment.
The agents dict references MAEDADOR_PROCESSUAL, but the only constant defined above is MAEADOR_PROCESSUAL. When run_squad() builds ClaudeAgentOptions, this unresolved name raises NameError, so the squad cannot execute any request. Point this entry to the declared constant (or rename consistently) so startup succeeds.
Useful? React with 👍 / 👎.
| @@ -0,0 +1,4 @@ | |||
| """Allow running as: python -m squads.analista-processual""" | |||
| from squads.analista_processual.squad import main | |||
There was a problem hiding this comment.
main from the package that actually exists
__main__.py imports squads.analista_processual.squad, but this commit creates squads/analista-processual/ and does not add a squads/analista_processual/ package. As a result, invoking python -m squads.analista-processual will hit ModuleNotFoundError at the new entrypoint instead of running the squad.
Useful? React with 👍 / 👎.
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 2 potential issues.
Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
| "mapeador": MAPEADOR, | ||
| "avaliador": AVALIADOR, | ||
| "documentador": DOCUMENTADOR, | ||
| "mapeador-processual": MAEDADOR_PROCESSUAL, |
There was a problem hiding this comment.
Mismatched variable name causes runtime NameError crash
High Severity
The mapeador agent definition is assigned to MAEADOR_PROCESSUAL (missing "P"), but the agents dictionary references MAEDADOR_PROCESSUAL (a different misspelling with an extra "D"). These are two distinct identifiers, so run_squad will crash with a NameError every time it's called. The intended name is likely MAPEADOR_PROCESSUAL.
Additional Locations (1)
| "Você é um especialista em síntese e documentação de relatórios processuais.\n\n" | ||
| "DETECÇÃO DE MODO:\n" | ||
| "- MODO_JURIDICO: se @leitor-de-pecas foi ativado (há extrações de peças)\n" | ||
| "- MODO_PROCESSUAL: se apenas @mapeador e @avaliador foram ativados\n\n" |
There was a problem hiding this comment.
Documentador mode detection incompatible with UC-AP-003 routing
Medium Severity
The orchestrator routes UC-AP-003 (Análise Estratégica) to @documentador-processual with MODO_JURIDICO, but the documentador's own mode detection logic triggers MODO_JURIDICO only when @leitor-de-pecas was activated — which UC-AP-003 never activates. The MODO_PROCESSUAL condition also doesn't match since it expects "only mapeador and avaliador." This leaves UC-AP-003 in an undefined detection state, risking the wrong report format for strategic analyses.
Additional Locations (1)
📝 WalkthroughWalkthroughA module entrypoint is added to enable direct execution of the analista-processual squad. The squad.py undergoes substantial restructuring, implementing a 3-tier architecture with intake, execution, and synthesis phases. Multiple agents are reorganized and renamed, tooling constraints are updated per agent, and a new system prompt orchestrates use-case classification and agent routing. Changes
Sequence DiagramsequenceDiagram
participant User
participant Orchestrator
participant T0_Mapeador as T0: Mapeador
participant T1_Agents as T1: Juridical Agents
participant Documentador
participant Output
User->>Orchestrator: input_text
Orchestrator->>Orchestrator: Classify use case via SYSTEM_PROMPT
alt Jurisprudence Query
Orchestrator->>T1_Agents: Route to Pesquisador-Juridico
T1_Agents-->>Orchestrator: jurisprudence results
Orchestrator-->>Output: Return directly
else Standard Processing
Orchestrator->>T0_Mapeador: Execute Tier 0 mapping
T0_Mapeador-->>Orchestrator: intake analysis
Orchestrator->>T1_Agents: Execute Tier 1 agents
T1_Agents-->>Orchestrator: juridical analysis
Orchestrator->>Documentador: Route to synthesis
Documentador-->>Output: Resultado Final
end
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@squads/analista-processual/__main__.py`:
- Around line 2-4: The entrypoint imports main using a top-level module path
that doesn't match the package name; change the import to a relative import so
Python resolves the sibling module inside this package (replace the current
import of main from squads.analista_processual.squad with a relative import that
pulls main from .squad and then call main()).
In `@squads/analista-processual/squad.py`:
- Around line 220-223: The DOCUMENTADOR_PROCESSUAL mode selection currently only
sets MODO_JURIDICO when `@leitor-de-pecas` ran, which misses UC-AP-003; update the
routing logic that computes the documentador mode (the code that selects between
MODO_JURIDICO and MODO_PROCESSUAL) so that if the use case id equals "UC-AP-003"
it forces DOCUMENTADOR_PROCESSUAL -> MODO_JURIDICO regardless of whether
`@leitor-de-pecas` executed; apply the same change to the other identical
selection block (the later occurrence that mirrors lines 278-282) so both
branches consistently choose MODO_JURIDICO for UC-AP-003 and thus include the
required citacoes block.
- Line 32: The identifier for the mapeador-processual agent is misspelled: the
definition uses MAEADOR_PROCESSUAL but the reference that builds
ClaudeAgentOptions expects MAEDADOR_PROCESSUAL; update either the declaration or
the reference to use the same name consistently (preferably rename the
declaration to MAEDADOR_PROCESSUAL to match the reference used when constructing
ClaudeAgentOptions) so the symbol resolves at runtime.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 03cff67d-62b5-40fd-86e9-6a3e63851b14
📒 Files selected for processing (3)
squads/analista-processual/__init__.pysquads/analista-processual/__main__.pysquads/analista-processual/squad.py
Comment on lines
+2
to
+4
| from squads.analista_processual.squad import main | ||
|
|
||
| main() |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Verify which analista-processual package paths actually exist in the repo.
# Expected: the executed package path should match the import target.
fd -t d 'analista[-_]processual' squads
fd -t f '__main__\.py$' squads
fd -t f 'squad\.py$' squads
rg -n 'from squads\.analista_processual\.squad import main|from \.squad import main' squadsRepository: felippepestana/Skill
Length of output: 314
Import main from the current package.
This entrypoint's directory is squads/analista-processual, but Line 2 imports from squads.analista_processual.squad (underscore-separated). Python cannot resolve this path since the actual directory uses hyphens. Running python -m squads.analista-processual fails before main() executes. Use a relative import to match the sibling squad entrypoint.
Fix
-from squads.analista_processual.squad import main
+from .squad import main🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@squads/analista-processual/__main__.py` around lines 2 - 4, The entrypoint
imports main using a top-level module path that doesn't match the package name;
change the import to a relative import so Python resolves the sibling module
inside this package (replace the current import of main from
squads.analista_processual.squad with a relative import that pulls main from
.squad and then call main()).
| # --------------------------------------------------------------------------- | ||
|
|
||
| MAPEADOR = AgentDefinition( | ||
| MAEADOR_PROCESSUAL = AgentDefinition( |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Verify the declaration/use mismatch for the mapeador agent constant.
# Expected: a single consistent identifier. Mixed results confirm the typo.
rg -n 'MAEADOR_PROCESSUAL|MAEDADOR_PROCESSUAL|MAPEADOR_PROCESSUAL' squads/analista-processual/squad.pyRepository: felippepestana/Skill
Length of output: 164
Fix the identifier mismatch for the mapeador-processual agent.
Line 32 declares MAEADOR_PROCESSUAL, but line 312 references MAEDADOR_PROCESSUAL—a NameError at runtime when ClaudeAgentOptions is built.
Fix
-MAEADOR_PROCESSUAL = AgentDefinition(
+MAPEADOR_PROCESSUAL = AgentDefinition(- "mapeador-processual": MAEDADOR_PROCESSUAL,
+ "mapeador-processual": MAPEADOR_PROCESSUAL,🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@squads/analista-processual/squad.py` at line 32, The identifier for the
mapeador-processual agent is misspelled: the definition uses MAEADOR_PROCESSUAL
but the reference that builds ClaudeAgentOptions expects MAEDADOR_PROCESSUAL;
update either the declaration or the reference to use the same name consistently
(preferably rename the declaration to MAEDADOR_PROCESSUAL to match the reference
used when constructing ClaudeAgentOptions) so the symbol resolves at runtime.
Comment on lines
+220
to
+223
| "DETECÇÃO DE MODO:\n" | ||
| "- MODO_JURIDICO: se @leitor-de-pecas foi ativado (há extrações de peças)\n" | ||
| "- MODO_PROCESSUAL: se apenas @mapeador e @avaliador foram ativados\n\n" | ||
| "=== MODO_PROCESSUAL ===\n" |
There was a problem hiding this comment.
Make DOCUMENTADOR_PROCESSUAL mode selection cover UC-AP-003.
UC-AP-003 is routed to MODO_JURIDICO, but the documentador only enters that mode when @leitor-de-pecas ran. In this path neither documented branch matches cleanly, so the final report can use the wrong template or miss the mandatory citacoes block.
One way to make the routing consistent
- "- MODO_JURIDICO: se `@leitor-de-pecas` foi ativado (há extrações de peças)\n"
- "- MODO_PROCESSUAL: se apenas `@mapeador` e `@avaliador` foram ativados\n\n"
+ "- MODO_JURIDICO: se qualquer agente jurídico foi ativado "
+ "(`@leitor-de-pecas`, `@pesquisador-juridico`, `@estrategista-processual` ou "
+ "@advogado-orientador)\n"
+ "- MODO_PROCESSUAL: se apenas `@mapeador-processual` e "
+ "@avaliador-processual foram ativados\n\n"Also applies to: 278-282
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@squads/analista-processual/squad.py` around lines 220 - 223, The
DOCUMENTADOR_PROCESSUAL mode selection currently only sets MODO_JURIDICO when
`@leitor-de-pecas` ran, which misses UC-AP-003; update the routing logic that
computes the documentador mode (the code that selects between MODO_JURIDICO and
MODO_PROCESSUAL) so that if the use case id equals "UC-AP-003" it forces
DOCUMENTADOR_PROCESSUAL -> MODO_JURIDICO regardless of whether `@leitor-de-pecas`
executed; apply the same change to the other identical selection block (the
later occurrence that mirrors lines 278-282) so both branches consistently
choose MODO_JURIDICO for UC-AP-003 and thus include the required citacoes block.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Completely restructured the Analista Processual Squad from a 4-agent model to a sophisticated 3-tier architecture with 7 specialized agents, introducing dual-mode processing for both generic organizational processes and Brazilian judicial cases.
Key Changes
Architecture Redesign: Implemented 3-tier pipeline:
New Agents:
leitor-de-pecas: Extracts 7 structured categories from legal documents (parties, dates, claims, legal grounds, decisions, evidence)pesquisador-juridico: Researches Brazilian jurisprudence (STF/STJ/TJs) with 5-dimension frameworkestrategista-processual: Analyzes positioning, risks, and 3 scenarios with probability percentagesadvogado-orientador: Translates strategy into concrete action plans with timelinesOrchestrator System Prompt: Replaced simple sequential flow with intelligent use-case classification (UC-AP-001 through UC-AP-004) that routes to appropriate agent combinations based on demand type
Dual-Mode Documentation: Documentador Processual now detects context and generates either:
Enhanced Tool Support: Added WebSearch and Grep tools; expanded Read/Write/Glob usage across agents
Quality Gates: Introduced 4 quality gates (QG-AP-001 through QG-AP-004) to ensure classification, structured outputs, and file persistence
Module Structure: Added
__main__.pyto enable execution aspython -m squads.analista-processualNotable Implementation Details
relatorio-[processo-slug]-[AAAA-MM-DD].mdand MUST confirm Write usagehttps://claude.ai/code/session_019XqLzo93ohjSCYVSg9sHEW
Summary by Sourcery
Refatorar a squad Analista Processual em um pipeline de orquestração multi-camadas e multi-agentes, com suporte duplo para análise de processos genéricos e fluxos de trabalho de casos judiciais brasileiros.
Novos recursos:
Melhorias:
Original summary in English
Summary by Sourcery
Refactor the Analista Processual squad into a multi-tier, multi-agent orchestration pipeline with dual support for generic process analysis and Brazilian judicial case workflows.
New Features:
Enhancements:
Summary by CodeRabbit
Release Notes
python -m squads.analista-processual