Habilidade de Explicador de Cron Schedule

--- name: cron-schedule-explainer description: Explica, valida e escreve agendamentos cron - traduz uma expressão cron para inglês simples, lista os próximos horários de execução e sinaliza armadilhas como a regra de dia do mês OU dia da semana, datas que nunca ocorrem, lacunas de horário de verão, confusão de fuso horário e trabalhos sobrepostos ou frequentes demais. Use quando um usuário colar uma linha de crontab, CronJob do Kubernetes, agendamento do GitHub Actions, ou perguntar "quando isso vai rodar?" ou "escreva um cron para toda terça-feira alternada". --- # Explicador de Agendamento Cron Você torna trabalhos agendados previsíveis. Para cada agendamento, você dá um significado em linguagem simples, horários concretos das próximas execuções e os riscos que surpreenderiam alguém às 2 da manhã. ## Arquivos nesta habilidade - `scripts/cron_explain.py` - analisador, explicador, calculador de próximas execuções e verificador de armadilhas (apenas biblioteca padrão do Python 3) - `references/cron-syntax.md` - intervalos de campos, caracteres especiais, macros e diferenças entre plataformas - `references/scheduling-pitfalls.md` - erros comuns e como evitá-los - `templates/schedule-review.md` - formato de revisão - `examples/example-backup-review.md` - uma revisão trabalhada de três linhas de crontab ## Fluxo de trabalho ### 1. Identifique a plataforma O cron padrão de 5 campos (Vixie cron, cronie, Kubernetes CronJob, GitHub Actions) é o padrão. Pergunte ou verifique se o usuário quer dizer Quartz (6 ou 7 campos com segundos e `?`), AWS EventBridge (6 campos com ano) ou systemd timers; veja `references/cron-syntax.md`. Observe o fuso horário: GitHub Actions sempre usa UTC; o Kubernetes usa o fuso do controlador, a menos que `timeZone` esteja definido. ### 2. Execute o verificador ```bash python3 scripts/cron_explain.py "30 2 * * 1-5" python3 scripts/cron_explain.py "0 9 1 * MON" --count 8 --from "2026-10-08 10:00" python3 scripts/cron_explain.py --file crontab.txt ``` Ele imprime uma explicação em inglês simples, os próximos N horários de execução (horário local ingênuo do servidor) e avisos. O código de saída é 1 quando uma expressão é inválida ou nunca executa. Se você não puder executar o script, aplique as mesmas regras manualmente e diga isso. ### 3. Explique Para cada agendamento, forneça: 1. Significado em inglês simples em uma frase. 2. As próximas 3 a 5 execuções com o fuso horário indicado. 3. Avisos do script e de `references/scheduling-pitfalls.md` que se aplicam (sobreposição com trabalhos longos, horário de verão, UTC versus local, execuções perdidas enquanto a máquina está desligada). ### 4. Escreva ou corrija agendamentos Quando o usuário descrever um agendamento em palavras, escreva a expressão e depois passe-a pelo verificador para confirmar que as próximas execuções correspondem à intenção. Para coisas que o cron não pode expressar diretamente (toda terça-feira alternada, o último dia útil do mês), forneça uma expressão cron mais um guard no comando, por exemplo `[ "$(date +\%d)" -le 07 ] && run-job`, e explique o porquê. ### 5. Relatório Use `templates/schedule-review.md`, como em `examples/example-backup-review.md`. ## Regras - Sempre indique o fuso horário que você está assumindo. - Lembre-se de que `%` deve ser escapado como `\%` dentro dos campos de comando do crontab. - Nunca edite um crontab ativo para o usuário; mostre a linha a adicionar e o passo `crontab -e`. - Recomende um lock (por exemplo `flock -n /tmp/job.lock cmd`) sempre que um job puder demorar mais que seu intervalo.