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

consultando_situacao_pedidos.py

--grupo Y --produto X

--cliente Y --produto X

consultando_situacao_pedidos.py

--grupo atacadao

consultando_situacao_pedidos.py

--cliente Carrefour

consultando_situacao_pedidos.py

--atrasados

consultando_produtos_estoque.py

--produto X --completo

consultando_produtos_estoque.py

--produto X --entradas

consultando_produtos_estoque.py

--ruptura --dias 7

analisando_disponibilidade_estoque.py

--pedido VCD123

analisando_disponibilidade_estoque.py

--grupo atacadao --completude

calculando_leadtime_entrega.py

--pedido X --data-embarque Y

criando_separacao_pedidos.py

--pedido X --expedicao Y

consultando_programacao_producao.py

--listar --dias 7

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:

references/products.md

references/business.md

references/glossary.md

references/synonyms.md

references/communication.md

references/examples.md

<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

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)

data_entrega_pedido

expedicao

agendamento

protocolo

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]

--pedido

--pedido VCD123

--pedido "atacadao 183"

--grupo

--grupo atacadao

--grupo assai

--grupo tenda

--loja

--loja 183

--uf

--uf SP

--data

--data amanha

--sem-agendamento

--sugerir-adiamento

--diagnosticar-origem

--completude

--atrasados

--diagnosticar-causa

--ranking-impacto

--limit

--limit 20

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]

--pedido

--pedido VCD123

--grupo

--grupo atacadao

--cliente

--cliente Carrefour

--cliente "45.543.915"

--produto

--produto palmito

--atrasados

--verificar-bonificacao

--status

--consolidar-com

--consolidar-com "assai 123"

--ate-data

--ate-data amanha

--ate-data 15/12

--em-separacao

--limit

--limit 20

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]

--produto

--produto palmito

--produto "az verde"

--completo

--entradas

--saidas

--pendente

--sobra

--ruptura

--dias

--dias 14

--limit

--limit 50

--limit-entradas

--limit-entradas 20

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]

--pedido

--pedido VCD123

--pedido "atacadao 183"

--cidade

--cidade "Sao Paulo"

--uf

--uf SP

--data-embarque

--data-embarque amanha

--data-entrega

--data-entrega 25/12

--limit

--limit 3

Modos de operacao:

--data-embarque

--data-entrega

--pedido

5. criando_separacao_pedidos.py

Proposito: Cria separacoes de pedidos via linguagem natural.

IMPORTANTE: Sempre executar primeiro SEM

--executar

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

--pedido

--pedido VCD123

--expedicao

--expedicao amanha

--expedicao 20/12

--tipo

--tipo completa

--tipo parcial

--pallets

--pallets 28

--pallets-inteiros

--apenas-estoque

--excluir-produtos

--excluir-produtos '["KETCHUP","MOSTARDA"]'

--agendamento

--agendamento 22/12

--protocolo

--protocolo AG12345

--agendamento-confirmado

--executar

Modos de operacao:

--executar

--executar

Tipos de separacao:

--tipo completa

--tipo parcial

--pallets N

--pallets N --pallets-inteiros

--apenas-estoque

--excluir-produtos '[...]'

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]

--listar

--dias

--dias 7

--por-dia

--por-linha

--linha

--linha "Linha A"

--produto

--produto "VF pouch 150"

Modos de operacao:

--listar

--produto

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/

Gatilhos para Consulta de References

context.md

context.md

context.md

glossary.md

products.md

glossary.md

context.md

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