name: code-with-logs
description: Gera código executável com logs narrativos obrigatórios incluindo timestamp [HH:MM:SS]. Use quando criar scripts, testes, jobs, ETLs, migrações, subagentes ou qualquer código executável que precise de logs de progresso com rastreabilidade temporal.

Code with Logs v3.0 (Generic)

APLICAÇÃO AUTOMÁTICA OBRIGATÓRIA

Esta skill DEVE ser aplicada automaticamente SEMPRE que detectar:

• Criação de novo script Python executável
• Criação de novo teste (test_*.py)
• Criação de subagente (classe com método executar() ou execute())
• Criação de job/ETL (função main() ou similar)
• Criação de migration SQL
• Qualquer código executável com função main() ou chamável diretamente

NÃO é necessário comando explícito do usuário.

Regra de Ouro (INQUEBRÁVEL)

Log de progresso NÃO é log técnico.

• NÃO usar [module][function]
• NÃO usar colchetes [] como prefixo
• NÃO usar logger padrão de debug
• NÃO misturar progresso com dados detalhados

Instruções Obrigatórias

SEMPRE que gerar código executável, inclua logs narrativos com timestamp obrigatório [HH:MM:SS].

Timestamp Obrigatório

TODOS os logs importantes DEVEM incluir timestamp:

• Logs de início
• Logs de progresso
• Logs de conclusão
• Logs de finalização
• Logs de erro

Helper Python (Adaptável ao Projeto)

Se o projeto tiver um helper de logs, USE-O. Exemplos comuns:

# Se o projeto tem LoggerComTimestamp:
from app.utils.log_helpers import LoggerComTimestamp
logger = LoggerComTimestamp()

# Se o projeto não tem helper, use inline:
from datetime import datetime

def log_ts(msg: str, emoji: str = "🔄"):
    ts = datetime.now().strftime('%H:%M:%S')
    print(f"{emoji} [{ts}] {msg}")

Prioridade: helper do projeto > helper inline > print com timestamp manual.

Formato de Logs (Python)

Saída esperada:

▶️ [14:23:15] Iniciando processamento de dados (ET: 2m)
🔄 [14:23:18] Passo 1/5 — Carregando arquivos (ETA: 90s)
✅ [14:23:25] Passo 1 concluído (⏱️ 10.2s)
🎉 [14:25:13] Execução concluída (⏱️ 118.5s | Início: 14:23:15 | Fim: 14:25:13)

Formato de Logs (SQL)

SEMPRE inclua timestamp em RAISE NOTICE:

DECLARE
    v_inicio TIMESTAMP := clock_timestamp();
    v_agora TIMESTAMP;
BEGIN
    RAISE NOTICE '[%] ▶️ Iniciando processamento', TO_CHAR(v_inicio, 'HH24:MI:SS');

    v_agora := clock_timestamp();
    RAISE NOTICE '[%] 🔄 Passo 1/5 — Processando (ETA: 40s)', TO_CHAR(v_agora, 'HH24:MI:SS');

    v_agora := clock_timestamp();
    RAISE NOTICE '[%] ✅ Passo 1 concluído (⏱️ %s)', 
        TO_CHAR(v_agora, 'HH24:MI:SS'),
        EXTRACT(EPOCH FROM (v_agora - v_inicio))::INTEGER || 's';
END;

Subagentes com Timestamp

Quando criar subagentes, use prefixo no logger:

# Com helper do projeto:
logger = LoggerComTimestamp(prefixo="[SUBAGENTE 1]")

# Ou inline:
def log_sub(msg, emoji="🔄", prefix="[SUBAGENTE 1]"):
    ts = datetime.now().strftime('%H:%M:%S')
    print(f"{emoji} [{ts}] {prefix} {msg}")

Logs de Erro

SEMPRE inclua timestamp e contexto em logs de erro:

❌ [14:24:30] Erro: Falha ao processar lote 4/10
❌ [14:24:30] Motivo: timeout na persistência
❌ [14:24:30] Ação: execução interrompida

Exemplo Completo (Python Genérico)

from datetime import datetime
import time

def log_ts(msg: str, emoji: str = "🔄"):
    ts = datetime.now().strftime('%H:%M:%S')
    print(f"{emoji} [{ts}] {msg}")

def main():
    inicio = time.time()
    log_ts("Iniciando processamento de dados (ET: 2m)", "▶️")

    # Passo 1
    log_ts("Passo 1/3 — Carregando dados (ETA: 60s)", "🔄")
    # ... código ...
    log_ts(f"Passo 1 concluído (⏱️ {time.time()-inicio:.1f}s)", "✅")

    # Passo 2
    log_ts("Passo 2/3 — Processando (ETA: 45s)", "🔄")
    # ... código ...
    log_ts(f"Passo 2 concluído (⏱️ {time.time()-inicio:.1f}s)", "✅")

    # Passo 3
    log_ts("Passo 3/3 — Finalizando (ETA: 15s)", "🔄")
    # ... código ...

    total = time.time() - inicio
    log_ts(f"Execução concluída (⏱️ {total:.1f}s)", "🎉")

if __name__ == "__main__":
    main()

Proibições Explícitas

• Criar código executável sem logs
• Criar logs sem timestamp
• SQL sem timestamp em RAISE NOTICE
• Scripts longos sem indicação de progresso

Regra Final

Sistema sem narrativa é sistema cego.
Código que executa sem log não é confiável.
Logs sem timestamp não são rastreáveis.