name	gerindo-expedicao
description	Consulta e opera dados logisticos da Nacom Goya. Consulta pedidos, estoque, disponibilidade, lead time. Cria separacoes. Resolve entidades (pedido, produto, cliente, grupo). Use para perguntas como 'tem pedido do Atacadao?', 'quanto tem de palmito?', 'quando fica disponivel?', 'crie separacao do VCD123'.
allowed-tools	Read, Bash, Glob, Grep

Gerindo Expedicao

Skill para consultas e operacoes logisticas da Nacom Goya.

Indice

Quando Usar Esta Skill
DECISION TREE - Qual Script Usar?
Scripts Disponiveis
Fluxo de Criacao de Separacao
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)

1. GUARDRAIL ANTI-ALUCINACAO

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

PERMITIDO	PROIBIDO
Mostrar dados retornados pelo script	Inventar "cobertura de X dias" sem calculo
Formatar/agrupar dados existentes	Criar campos que nao existem no JSON
Resumir informacoes do JSON	Estimar valores sem base no 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.

Situacao	Acao
Script retornou erro	Explicar o erro e sugerir alternativa
Parametro nao suportado	Usar parametros disponiveis ou perguntar
Entidade nao encontrada	Informar "nao encontrei X, voce quis dizer Y?"
Timeout/falha tecnica	"Houve um problema ao consultar. Posso tentar de outra forma?"

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

3. SIMULAR ANTES DE EXECUTAR (ACOES)

Para QUALQUER acao que modifica dados (criar separacao):

Executar SEM --executar (simular)
Mostrar resultado ao usuario
AGUARDAR confirmacao explicita
So entao executar COM --executar

DECISION TREE - Qual Script Usar?

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

Mapeamento Rapido

Se a pergunta menciona...	Use este script	Com estes parametros
PRODUTO + CLIENTE/GRUPO ("quanto de X pro Y?")	`consultando_situacao_pedidos.py`	`--grupo Y --produto X` ou `--cliente Y --produto X`
Pedidos de um grupo ("tem pedido do atacadao?")	`consultando_situacao_pedidos.py`	`--grupo atacadao`
Pedidos de um cliente ("tem pedido do Carrefour?")	`consultando_situacao_pedidos.py`	`--cliente Carrefour`
Pedidos atrasados	`consultando_situacao_pedidos.py`	`--atrasados`
Estoque de produto ("quanto tem de X?")	`consultando_produtos_estoque.py`	`--produto X --completo`
Entradas recentes ("chegou X?")	`consultando_produtos_estoque.py`	`--produto X --entradas`
Ruptura/falta ("vai faltar X?")	`consultando_produtos_estoque.py`	`--ruptura --dias 7`
Quando pedido fica disponivel	`analisando_disponibilidade_estoque.py`	`--pedido VCD123`
Disponibilidade de grupo	`analisando_disponibilidade_estoque.py`	`--grupo atacadao --completude`
Prazo de entrega ("quando chega?")	`calculando_leadtime_entrega.py`	`--pedido X --data-embarque Y`
Criar separacao	`criando_separacao_pedidos.py`	`--pedido X --expedicao Y` (SEM --executar primeiro!)
Programacao de producao	`consultando_programacao_producao.py`	`--listar --dias 7`

Regras de Decisao (em ordem de prioridade)

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
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
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
Se pergunta e sobre DISPONIBILIDADE de pedido: → Use analisando_disponibilidade_estoque.py --pedido X → Exemplo: "quando VCD123 fica disponivel?" → --pedido VCD123
Se pergunta e sobre PRAZO de entrega: → Use calculando_leadtime_entrega.py → Exemplo: "se embarcar amanha, quando chega?" → --pedido X --data-embarque amanha
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)

Como Decidir (Raciocinio Obrigatorio)

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!

Leitura de References (Sob Demanda)

**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

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

Gatilho na Pergunta	Reference a Ler	Motivo
Produto mencionado	`references/products.md`	Entender abreviacoes (CI, AZ VF, BD)
Cliente/Grupo	`references/business.md`	Prefixos CNPJ, constantes
Termo desconhecido	`references/glossary.md`	"matar", "ruptura", "FOB"
Variacao de escrita	`references/synonyms.md`	ketchup→catchup
Comunicar PCP/Comercial	`references/communication.md`	Templates de mensagem
Duvida de script	`references/examples.md`	Validar escolha

**Exemplo de Fluxo Completo**

Pergunta: "quanto tem de palmito pro atacadao 183"

IA le references/glossary.md → "pendente" = qtd_saldo > 0
IA le references/business.md → atacadao = grupo com prefixos CNPJ
IA executa: python consultando_situacao_pedidos.py --grupo atacadao --produto palmito
Script encontra 18 candidatos de palmito
Script busca TODOS na carteira do cliente (nao para por multiplos)
Script retorna 2 SKUs com saldo: Tolete 15x300g (2.592 un), Rodela 15x300g (1.053 un)
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.

Termos Ambiguos - PERGUNTE antes de agir!

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

"programacao de entrega" (CRITICO - 4 interpretacoes)

Opcao	Significado	Campo	Tabela
A	Data que cliente solicitou	`data_entrega_pedido`	CarteiraPrincipal
B	Data que vamos expedir	`expedicao`	Separacao
C	Data que vai chegar no cliente	`agendamento`	Separacao
D	Protocolo de agendamento	`protocolo`	Separacao

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"

Opcao	Significado	Fonte
Carteira	Ainda nao separado	CarteiraPrincipal
Separacao	Separado mas nao faturado	Separacao (sincronizado_nf=False)
Total	Ambos	Carteira + Separacao

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

Termo	Possibilidades	O que PERGUNTAR
"quando fica disponivel?"	Pedido ou produto?	"Voce quer saber quando um PEDIDO fica disponivel ou quando um PRODUTO estara em estoque?"
"situacao"	De que?	"Situacao de qual pedido ou produto?"
"crie separacao"	Data faltando	"Para qual data de expedicao?"

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]

Parametro	Descricao	Exemplo
`--pedido`	Numero do pedido ou "grupo termo"	`--pedido VCD123` ou `--pedido "atacadao 183"`
`--grupo`	Grupo empresarial	`--grupo atacadao`, `--grupo assai`, `--grupo tenda`
`--loja`	Identificador da loja (em raz_social_red)	`--loja 183`
`--uf`	Filtrar por UF	`--uf SP`
`--data`	Data para analise (hoje, amanha, dd/mm, YYYY-MM-DD)	`--data amanha`
`--sem-agendamento`	Apenas pedidos sem exigencia de agendamento	flag
`--sugerir-adiamento`	Sugerir pedidos para adiar (liberar estoque)	flag
`--diagnosticar-origem`	Distinguir falta absoluta vs relativa	flag
`--completude`	Calcular % faturado vs pendente	flag
`--atrasados`	Analisar pedidos com expedicao vencida	flag
`--diagnosticar-causa`	Detalhar causa do atraso	flag
`--ranking-impacto`	Ranking de pedidos que mais travam carteira	flag
`--limit`	Limite de resultados (default: 100)	`--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]

Parametro	Descricao	Exemplo
`--pedido`	Numero do pedido ou termo de busca	`--pedido VCD123`
`--grupo`	Grupo empresarial (atacadao, assai, tenda)	`--grupo atacadao`
`--cliente`	⭐ NOVO CNPJ ou nome parcial do cliente	`--cliente Carrefour`, `--cliente "45.543.915"`
`--produto`	Filtrar por produto (combina com --grupo ou --cliente)	`--produto palmito`
`--atrasados`	Listar pedidos atrasados	flag
`--verificar-bonificacao`	Verificar bonificacoes faltando	flag
`--status`	Mostrar status detalhado	flag
`--consolidar-com`	Buscar pedidos para consolidar	`--consolidar-com "assai 123"`
`--ate-data`	Data limite de expedicao	`--ate-data amanha`, `--ate-data 15/12`
`--em-separacao`	Buscar em Separacao (nao CarteiraPrincipal)	flag
`--limit`	Limite de resultados (default: 100)	`--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]

Parametro	Descricao	Exemplo
`--produto`	Nome ou termo do produto	`--produto palmito`, `--produto "az verde"`
`--completo`	⭐ SITUACAO COMPLETA (estoque, separacoes, demanda, producao, projecao)	flag
`--entradas`	Mostrar entradas recentes (qtd > 0)	flag
`--saidas`	Mostrar saidas recentes (qtd < 0)	flag
`--pendente`	Quantidade pendente de embarque + lista pedidos	flag
`--sobra`	Calcular sobra de estoque apos demanda	flag
`--ruptura`	Previsao de rupturas	flag
`--dias`	Horizonte de projecao em dias (default: 7)	`--dias 14`
`--limit`	Limite de resultados (default: 100)	`--limit 50`
`--limit-entradas`	Limite de movimentacoes por produto (default: 100)	`--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]

Parametro	Descricao	Exemplo
`--pedido`	Numero do pedido ou termo de busca	`--pedido VCD123`, `--pedido "atacadao 183"`
`--cidade`	Cidade de destino (alternativa ao pedido)	`--cidade "Sao Paulo"`
`--uf`	UF de destino (requerido se usar --cidade)	`--uf SP`
`--data-embarque`	Data de embarque (calcula data de entrega)	`--data-embarque amanha`
`--data-entrega`	⭐ NOVO Data de entrega desejada (calcula data de embarque)	`--data-entrega 25/12`
`--limit`	Limite de opcoes de transportadora (default: 10)	`--limit 3`

Modos de operacao:

Modo	Parametro	Descricao
Previsao de entrega	`--data-embarque`	Se embarcar dia X, quando chega?
Sugestao de embarque	`--data-entrega`	Para chegar dia Y, quando embarcar?
Auto (usa pedido)	Apenas `--pedido`	Usa data_entrega_pedido para calculo reverso

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]

Parametro	Descricao	Exemplo
`--pedido`	Numero do pedido (OBRIGATORIO)	`--pedido VCD123`
`--expedicao`	Data de expedicao (OBRIGATORIO)	`--expedicao amanha`, `--expedicao 20/12`
`--tipo`	Tipo de separacao	`--tipo completa`, `--tipo parcial`
`--pallets`	Quantidade de pallets desejada	`--pallets 28`
`--pallets-inteiros`	Forcar pallets inteiros por item	flag
`--apenas-estoque`	Separar apenas o que tem em estoque	flag
`--excluir-produtos`	JSON array de produtos a excluir	`--excluir-produtos '["KETCHUP","MOSTARDA"]'`
`--agendamento`	Data de agendamento	`--agendamento 22/12`
`--protocolo`	Protocolo de agendamento	`--protocolo AG12345`
`--agendamento-confirmado`	Marcar agendamento como confirmado	flag
`--executar`	Efetivamente criar (sem isso, apenas simula)	flag

Modos de operacao:

Modo	Descricao
Sem `--executar`	SIMULA e mostra o que seria criado
Com `--executar`	CRIA efetivamente a separacao

Tipos de separacao:

Tipo	Parametros	Descricao
Completa	`--tipo completa`	Todos os itens com qtd total
Parcial	`--tipo parcial`	N itens com qtds especificas
Por pallets	`--pallets N`	Distribuir N pallets proporcionalmente
Pallets inteiros	`--pallets N --pallets-inteiros`	Cada item = pallets inteiros
Apenas estoque	`--apenas-estoque`	So o que tem disponivel
Excluindo produtos	`--excluir-produtos '[...]'`	Tudo exceto lista

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]

Parametro	Descricao	Exemplo
`--listar`	⭐ NOVO Lista TODA a programacao de producao	flag
`--dias`	Horizonte em dias (default: 14)	`--dias 7`
`--por-dia`	Mostrar detalhes agrupados por dia	flag
`--por-linha`	Mostrar detalhes agrupados por linha	flag
`--linha`	Filtrar por linha de producao	`--linha "Linha A"`
`--produto`	Produto em ruptura (para reprogramacao)	`--produto "VF pouch 150"`

Modos de operacao:

Modo	Parametro	Descricao
Listagem	`--listar`	Toda a programacao dos proximos N dias
Reprogramacao	`--produto`	Opcoes para resolver ruptura

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

Campo	Obrigatorio	Como Obter
Pedido	SIM	Usuario informa
Data expedicao	SIM	Usuario informa
Tipo (completa/parcial)	SIM	Perguntar se nao especificado
Agendamento	CONDICIONAL	Verificar ContatoAgendamento pelo CNPJ
Protocolo	CONDICIONAL	Se exige agendamento

Sequencia

SIMULAR primeiro (sem --executar)
Verificar alertas de estoque
Mostrar resultado ao usuario
Solicitar confirmacao
EXECUTAR (com --executar)

Nivel de Detalhes (Progressive Disclosure)

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

Referencias

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

Gatilhos para Consulta de References

Se pergunta menciona...	Consultar	Motivo
PRIORIZACAO, qual cliente primeiro	`context.md` → Top Clientes	Atacadao=50%, Assai=13%
ATRASO, agenda, gargalo	`context.md` → Gargalos	Agendas sao o maior gargalo
PARCIAL vs AGUARDAR, decisao	`context.md` → Contexto Estrategico	Fundos limitam estoques
"Chegou?", entradas	`glossary.md` → Usar --entradas	Mapeamento de acao
Abreviacao (CI, AZ VF, BD)	`products.md`	Resolver abreviacao
Termo desconhecido (matar, FOB)	`glossary.md`	Entender jargao
Cliente importante (Atacadao, Assai)	`context.md` → SLAs	SLA 45 dias Atacadao

Tabela de Referencias

Arquivo	Quando Consultar
business.md	Constantes, limites veiculos, formulas de calculo
glossary.md	Termos do dominio (ruptura, matar, FOB, RED, "Chegou?")
synonyms.md	Termos criticos nao obvios (c car, RED, OP)
products.md	Abreviacoes de produto (CI, AZ VF, BD, IND)
examples.md	Exemplos de uso e anti-patterns
context.md	Contexto estrategico, clientes top, gargalos, SLAs
communication.md	Templates de mensagem para PCP ou Comercial

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

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

gerindo-expedicao

Install Skill

SKILL.md

Gerindo Expedicao

Indice

Quando Usar Esta Skill

REGRAS CRITICAS (NUNCA VIOLAR)

1. GUARDRAIL ANTI-ALUCINACAO

2. REGRA DE FALLBACK (NUNCA TRAVAR)

3. SIMULAR ANTES DE EXECUTAR (ACOES)

DECISION TREE - Qual Script Usar?

Mapeamento Rapido

Regras de Decisao (em ordem de prioridade)

Como Decidir (Raciocinio Obrigatorio)

Leitura de References (Sob Demanda)

Termos Ambiguos - PERGUNTE antes de agir!

"programacao de entrega" (CRITICO - 4 interpretacoes)

"quantidade pendente"

"itens" vs "unidades"

Multiplas lojas do mesmo grupo

Outros termos ambiguos

Exemplos de Boas e Mas Escolhas

Scripts Disponiveis

Ambiente Virtual

1. analisando_disponibilidade_estoque.py

2. consultando_situacao_pedidos.py

3. consultando_produtos_estoque.py

4. calculando_leadtime_entrega.py

5. criando_separacao_pedidos.py

6. consultando_programacao_producao.py

7. resolver_entidades.py

Fluxo de Criacao de Separacao

Checklist Obrigatorio

Sequencia

Nivel de Detalhes (Progressive Disclosure)

Referencias

Gatilhos para Consulta de References

Tabela de Referencias