Gerindo Expedicao

Skill para consultas e operacoes logisticas da Nacom Goya.

Indice

1. •Quando Usar Esta Skill
2. •DECISION TREE - Qual Script Usar?
   • •Mapeamento Rapido
   • •Regras de Decisao
   • •Como Decidir (Raciocinio)
   • •Termos Ambiguos
   • •Exemplos
3. •Scripts Disponiveis
   • •analisando_disponibilidade_estoque.py
   • •consultando_situacao_pedidos.py
   • •consultando_produtos_estoque.py
   • •calculando_leadtime_entrega.py
   • •criando_separacao_pedidos.py
   • •consultando_programacao_producao.py
4. •Fluxo de Criacao de Separacao
5. •Referencias (tables, business, glossary, synonyms, products, examples)

Quando Usar Esta Skill

USE para:

• •Consultas de pedidos: "tem pedido do Atacadao?", "pedido VCD123 esta em separacao?"
• •Consultas de estoque: "quanto tem de palmito?", "chegou cogumelo?"
• •Analise de disponibilidade: "quando VCD123 fica disponivel?", "o que vai dar falta?"
• •Calculo de prazo: "se embarcar amanha, quando chega?"
• •Criacao de separacao: "crie separacao do VCD123 pra amanha"
• •Resolucao de entidades: identificar pedido, produto, cliente por termos parciais

NAO USE para:

• •Analise COMPLETA da carteira com decisoes (use o Agent analista-carteira)
• •Comunicacao com PCP ou Comercial (use o Agent)
• •Decisoes de priorizacao P1-P7 (use o Agent)

REGRAS CRITICAS (NUNCA VIOLAR)

<regras_criticas>

1. GUARDRAIL ANTI-ALUCINACAO

PROIBIDO criar, calcular ou inferir dados que NAO foram retornados pelo script.

Se precisar de dado que nao veio no script: EXECUTE o script com flag adequado ou PERGUNTE ao usuario.

2. REGRA DE FALLBACK (NUNCA TRAVAR)

Se um script falhar ou retornar erro: SEMPRE responda ao usuario.

NUNCA: Ficar em silencio, travar, ou tentar criar scripts customizados.

3. SIMULAR ANTES DE EXECUTAR (ACOES)

Para QUALQUER acao que modifica dados (criar separacao):

1. •Executar SEM --executar (simular)
2. •Mostrar resultado ao usuario
3. •AGUARDAR confirmacao explicita
4. •So entao executar COM --executar

</regras_criticas>

DECISION TREE - Qual Script Usar?

<decision_tree> SEMPRE consulte esta secao ANTES de executar qualquer script. A escolha correta evita resultados errados e retrabalho. </decision_tree>

Mapeamento Rapido

Regras de Decisao (em ordem de prioridade)

<regras_decisao>

1. •

   Se pergunta tem PRODUTO + CLIENTE/GRUPO juntos: → Use consultando_situacao_pedidos.py --grupo X --produto Y ou --cliente X --produto Y → Exemplo: "quantas caixas de ketchup tem pro atacadao?" → --grupo atacadao --produto ketchup

2. •

   Se pergunta e sobre PEDIDOS de um cliente/grupo (sem produto): → Use consultando_situacao_pedidos.py --grupo X ou --cliente X → Exemplo: "tem pedido do assai?" → --grupo assai

3. •

   Se pergunta e sobre ESTOQUE de produto (sem cliente): → Use consultando_produtos_estoque.py --produto X --completo → Exemplo: "quanto tem de palmito?" → --produto palmito --completo

4. •

   Se pergunta e sobre DISPONIBILIDADE de pedido: → Use analisando_disponibilidade_estoque.py --pedido X → Exemplo: "quando VCD123 fica disponivel?" → --pedido VCD123

5. •

   Se pergunta e sobre PRAZO de entrega: → Use calculando_leadtime_entrega.py → Exemplo: "se embarcar amanha, quando chega?" → --pedido X --data-embarque amanha

6. •

   Se for ACAO de criar separacao: → Use criando_separacao_pedidos.py (SEMPRE simular antes de executar!) → Exemplo: "crie separacao do VCD123" → --pedido VCD123 --expedicao [data] (SEM --executar)

</regras_decisao>

Como Decidir (Raciocinio Obrigatorio)

<instrucao_raciocinio> ANTES de escolher qualquer script, faca este raciocinio mentalmente:

PASSO 1 - IDENTIFICAR: O que o usuario quer saber?

• •E sobre PEDIDOS? (quem comprou, quanto, quando entregar)
• •E sobre ESTOQUE? (tem, vai faltar, chegou, quanto sobra)
• •E sobre DISPONIBILIDADE? (quando pedido fica pronto)
• •E sobre PRAZO? (quando chega se embarcar dia X)
• •E uma ACAO? (criar separacao)

PASSO 2 - VERIFICAR: Tem cliente/grupo mencionado?

• •SIM + produto → consultando_situacao_pedidos --grupo/--cliente + --produto
• •SIM sem produto → consultando_situacao_pedidos --grupo/--cliente
• •NAO → provavelmente consultando_produtos_estoque

PASSO 3 - CONFIRMAR: A escolha faz sentido?

• •Se escolhi ESTOQUE mas usuario perguntou "pro atacadao" → ERRADO (use PEDIDOS)
• •Se escolhi PEDIDOS mas usuario perguntou "quanto tem em estoque" → ERRADO (use ESTOQUE)
• •Se escolhi DISPONIBILIDADE mas usuario perguntou "quando chega" → ERRADO (use LEADTIME)

PASSO 4 - PERGUNTAR: Se ainda em duvida apos os 3 passos → pergunte ao usuario! </instrucao_raciocinio>

Leitura de References (Sob Demanda)

<filosofia_50_50> FILOSOFIA: 50% Regra / 50% IA

Esta skill implementa um equilibrio entre scripts e IA:

SCRIPTS fazem:

• •Resolver entidades (cliente, grupo, produto)
• •Buscar dados no banco
• •Retornar TODOS os candidatos (sem truncar)

IA decide:

• •Como agrupar/apresentar resultados
• •Se precisa perguntar algo ao usuario
• •Quando usar references para contexto </filosofia_50_50>

<leitura_references> ANTES de executar scripts, o agente DEVE ler os references relevantes baseado na pergunta:

<exemplo_fluxo_50_50> Exemplo de Fluxo Completo

Pergunta: "quanto tem de palmito pro atacadao 183"

1. •IA le references/glossary.md → "pendente" = qtd_saldo > 0
2. •IA le references/business.md → atacadao = grupo com prefixos CNPJ
3. •IA executa: python consultando_situacao_pedidos.py --grupo atacadao --produto palmito
4. •Script encontra 18 candidatos de palmito
5. •Script busca TODOS na carteira do cliente (nao para por multiplos)
6. •Script retorna 2 SKUs com saldo: Tolete 15x300g (2.592 un), Rodela 15x300g (1.053 un)
7. •IA apresenta tabela consolidada ao usuario

IMPORTANTE: Quando script retorna ia_decide: true, a IA DEVE processar os dados e decidir a melhor forma de apresentar. </exemplo_fluxo_50_50>

Termos Ambiguos - PERGUNTE antes de agir!

<termos_ambiguos>

Se o usuario usar estes termos, PARE e PERGUNTE antes de executar.

"programacao de entrega" (CRITICO - 4 interpretacoes)

PERGUNTAR: "Voce quer saber: A) data que o cliente solicitou, B) data de expedicao programada, C) data de chegada no cliente, ou D) protocolo de agendamento?"

"quantidade pendente"

ACAO PADRAO: Mostrar AMBOS e explicar: "Na carteira: X un | Em separacao: Y un | Total pendente: Z un"

"itens" vs "unidades"

NUNCA usar "itens" sozinho. SEMPRE especificar:

• •"X linhas de produto" (SKUs diferentes)
• •"X unidades" ou "X caixas" (quantidade)

Multiplas lojas do mesmo grupo

Se resultado tiver mais de 1 loja do mesmo grupo (ex: Atacadao): PERGUNTAR: "Encontrei pedidos em X lojas do [grupo]. Qual loja especificamente, ou quer ver todas?"

Outros termos ambiguos

</termos_ambiguos>

Exemplos de Boas e Mas Escolhas

VER references/examples.md para exemplos detalhados de uso correto e anti-patterns.

Resumo rapido:

• •PRODUTO + CLIENTE → consultando_situacao_pedidos --grupo/--cliente + --produto
• •So ESTOQUE (sem cliente) → consultando_produtos_estoque --produto X --completo
• •QUANDO DISPONIVEL → analisando_disponibilidade_estoque --pedido X
• •QUANDO CHEGA (prazo) → calculando_leadtime_entrega --pedido X --data-embarque Y
• •CRIAR SEPARACAO → criando_separacao_pedidos (SEM --executar primeiro!)

Scripts Disponiveis

Ambiente Virtual

Sempre ativar antes de executar:

source .venv/bin/activate

1. analisando_disponibilidade_estoque.py

Proposito: Analisa disponibilidade de estoque para pedidos ou grupos de clientes.

Queries cobertas: Q1, Q2, Q3, Q4, Q5, Q6, Q9, Q11, Q12

source .venv/bin/activate && \
python .claude/skills/gerindo-expedicao/scripts/analisando_disponibilidade_estoque.py [parametros]

2. consultando_situacao_pedidos.py

Proposito: Consulta pedidos por diversos filtros e perspectivas.

Queries cobertas: Q8, Q10, Q14, Q16, Q19

source .venv/bin/activate && \
python .claude/skills/gerindo-expedicao/scripts/consultando_situacao_pedidos.py [parametros]

Combinacoes suportadas:

• •--grupo atacadao --produto ketchup → Pedidos do Atacadao com ketchup
• •--cliente Carrefour --produto palmito → Pedidos do Carrefour com palmito
• •--cliente "45.543.915" → Busca por CNPJ

3. consultando_produtos_estoque.py

Proposito: Consulta estoque atual, movimentacoes, pendencias, projecoes e SITUACAO COMPLETA.

Queries cobertas: Q13, Q17, Q18, Q20 + SITUACAO COMPLETA

source .venv/bin/activate && \
python .claude/skills/gerindo-expedicao/scripts/consultando_produtos_estoque.py [parametros]

Opcao --completo retorna:

• •Estoque atual e menor estoque nos proximos 7 dias
• •Separacoes por data de expedicao (detalhado com pedidos)
• •Demanda total (Carteira bruta/liquida + Separacoes)
• •Programacao de producao (proximos 14 dias)
• •Projecao dia a dia (estoque projetado)
• •Indicadores: sobra, cobertura em dias, % disponivel, previsao de ruptura

4. calculando_leadtime_entrega.py

Proposito: Calcula data de entrega OU data de expedicao sugerida (calculo reverso).

Queries cobertas: Q7 + CALCULO REVERSO

source .venv/bin/activate && \
python .claude/skills/gerindo-expedicao/scripts/calculando_leadtime_entrega.py [parametros]

Modos de operacao:

5. criando_separacao_pedidos.py

Proposito: Cria separacoes de pedidos via linguagem natural.

IMPORTANTE: Sempre executar primeiro SEM --executar para simular!

source .venv/bin/activate && \
python .claude/skills/gerindo-expedicao/scripts/criando_separacao_pedidos.py [parametros]

Modos de operacao:

Tipos de separacao:

6. consultando_programacao_producao.py

Proposito: Lista programacao de producao e simula alteracoes para resolver ruptura.

Queries cobertas: Q15 + LISTAGEM COMPLETA

source .venv/bin/activate && \
python .claude/skills/gerindo-expedicao/scripts/consultando_programacao_producao.py [parametros]

Modos de operacao:

Exemplo de listagem completa:

python .claude/skills/gerindo-expedicao/scripts/consultando_programacao_producao.py --listar --dias 7 --por-dia

7. resolver_entidades.py

Proposito: Modulo utilitario para resolver entidades do dominio.

Uso interno pelos outros scripts. Resolve:

• •Pedidos por numero parcial ou termo
• •Produtos por nome ou abreviacoes
• •Grupos empresariais por nome
• •Cidades por nome (normalizado)

Fluxo de Criacao de Separacao

Checklist Obrigatorio

Sequencia

1. •SIMULAR primeiro (sem --executar)
2. •Verificar alertas de estoque
3. •Mostrar resultado ao usuario
4. •Solicitar confirmacao
5. •EXECUTAR (com --executar)

Nivel de Detalhes (Progressive Disclosure)

1. •Resposta inicial: Resumo com 3-5 itens principais
2. •Se pedir mais: Mostrar mais itens do mesmo JSON
3. •Se pedir "todos": Lista completa

Referencias

<progressive_disclosure> Os arquivos em references/ sao carregados sob demanda. NAO leia todos de uma vez - consulte apenas quando necessario. </progressive_disclosure>

Gatilhos para Consulta de References

Tabela de Referencias

NOTA: Para schemas de tabelas, consulte CLAUDE.md na raiz do projeto (secao "MODELOS CRITICOS").

Grupos Empresariais: --grupo atacadao, --grupo assai, --grupo tenda