playbook/antigravity-awesome-skills/skills/task-intelligence/references/problem-catalog.md

Catálogo de Problemas por Domínio

Skills e Orchestrator

Problema	Frequência	Solução Preventiva
YAML inválido no SKILL.md	Alta	python -c "import yaml; yaml.safe_load(open('SKILL.md').read())"
name ou description duplicados no YAML	Média	Grep por ^name: no arquivo — deve ter 1 ocorrência
skill-installer falha silenciosamente	Média	Usar --force e ler output completo
scan_registry.py bug com sets/dicts	Baixa	Atualizar registry manualmente via JSON
Skill no .claude mas não em skills/	Média	Sempre instalar via skill-installer, não copiar manual

APIs e Integrações

Problema	Frequência	Solução Preventiva
Token/API key expirado	Alta	Verificar validade antes de executar
Rate limit atingido	Média	Implementar retry com backoff exponencial
Endpoint mudou (breaking change)	Baixa	Fixar versão da API, checar changelog antes
HMAC-SHA256 inválido em webhooks	Média	Testar com payload de exemplo antes de ir live
Credencial hardcoded commitada	Baixa mas crítica	.env obrigatório + .gitignore configurado

Arquivos e Paths

Problema	Frequência	Solução Preventiva
Path não existe	Alta	os.path.exists() antes de qualquer operação
Permissão negada	Média	Verificar com os.access(path, os.W_OK)
Encoding errado (pt-BR com acentos)	Alta	open(f, encoding='utf-8') explícito sempre
ZIP corrompido	Baixa	Verificar com zipfile.is_zipfile() após geração
Arquivo aberto por outro processo	Baixa	Fechar handles explicitamente com with

ZIPs e Builds do Ecossistema

Problema	Frequência	Solução Preventiva
ecosystem-completo.zip desatualizado	Alta	Executar build_ecosystem.py após cada nova skill
Skill numerada fora de ordem	Média	Verificar contagem total antes de atribuir número
ZIP muito grande (>50MB)	Baixa	Excluir pycache, .pyc, node_modules

Git

Problema	Frequência	Solução Preventiva
Commit na branch errada	Alta	git branch --show-current antes de commits
Uncommitted changes perdidos	Média	git status antes de operações destrutivas
Merge conflict	Média	git pull --rebase antes de push
Push de secrets	Baixa mas crítica	git diff --staged antes de commit

Python / Scripts

Problema	Frequência	Solução Preventiva
ModuleNotFoundError	Alta	pip install -r requirements.txt primeiro
Python 2 vs 3	Baixa	Usar python3 explicitamente
Subprocess sem timeout	Média	Sempre subprocess.run(..., timeout=30)
JSON decode error	Média	Tratar json.JSONDecodeError explicitamente
UnicodeDecodeError	Alta	encoding='utf-8', errors='replace' em files