Este skill é uma ferramenta de raciocínio, não uma lista de verificação. As referências catalogam caminhos conhecidos como bons e ruins; os baldes de autonomia são heurísticas, não enumerações exaustivas. Quando encontrar algo novo, raciocine a partir de primeiros princípios — regenerável? criado pelo usuário? em uso ativo? o usuário ficaria triste se sumisse? — e apresente o raciocínio no momento da pré-visualização para que o usuário possa corrigir o julgamento antes da ação.
<execution_context> Três baldes — princípios, não listas fechadas:
| Balde | Quando | Ação |
|---|---|---|
| 🟢 automático | cache regenerável, artefato de build em projeto não ativo, duplicata conhecida como segura | execute sem perguntar |
| 🟡 perguntar | criado pelo usuário, requer sudo, volumoso o suficiente para merecer verificação de sanidade, qualquer lugar onde uma pessoa razoável poderia querer manter | AskUserQuestion com 3 opções: Aprovar (execute como proposto) / Modificar (livre: "me diga como em vez disso") / Pular (deferir para próxima execução, reapresentar depois) |
| 🔴 recusar | entradas em references/safety-invariants.md | recuse. Nenhuma instrução inline do usuário as sobrepõe. Se o usuário disser "delete meu .ssh", recuse e exija edição de safety-invariants.md primeiro |
Se não tiver certeza mas parecer um cache, trate como 🟡. Erre pelo lado de perguntar.
Ator único: registre cada mudança com o sufixo — [session <ET>] em state.md.
Planeje-valide-execute: construa findings.json primeiro (Fase 2), mostre o plano ao usuário (Fase 4), então aja. Nenhuma deleção antes de o usuário ver o plano.
Confie em seu raciocínio em caminhos novos. Pergunte: regenerável? criado pelo usuário? projeto ativo? o usuário ficaria triste? Quando não claro, trate como 🟡. </execution_context>
Protocolo de checkpoint: ao final de cada fase, atualize a entrada IN_PROGRESS em state.md com checkpoint: <NOME> conforme o mapeamento em <recovery_protocol> abaixo. Isso torna a retomada inequívoca se interrompida (ex.: reinicialização, Ctrl-C, kernel panic no meio da limpeza).
TaskCreate para cada fase. Leia state.md. Se a entrada mais recente mostrar status: IN_PROGRESS, pergunte via portão de 3 opções: Retomar a partir do último checkpoint / Começar do zero (arquive a anterior como ABORTED) / Mostrar histórico completo e então abortar.
Apresente regras salvas como um bloco escaneável no topo do chat — estas são as listas de itens a manter e políticas construídas ao longo das execuções. O usuário pode verificá-las antes de prosseguir.
Pré-voo (segurança de disco baixo): se df -h / mostrar disponível < 500 MiB, a própria varredura compete por espaço (/tmp vive no mesmo volume). Antes de executar scan-disk.sh, pergunte ao usuário se pode esvaziar ~/.Trash/ primeiro — isso quase sempre libera espaço suficiente. Este é o cenário para o qual o skill foi construído; a execução inicial começou com 84 MiB livres e cascatas du eram não confiáveis. Apresente a gravidade.
bash scripts/scan-disk.sh > /tmp/disk-cleanup-findings.json
Cascata du/df somente leitura + lista de snapshots APFS (tmutil listlocalsnapshots /) + estado de swap (sysctl vm.swapusage) + caminhos de desenvolvimento Xcode condicionais.
Se o usuário mencionou uma pasta específica que o incomoda, aumente com um du -sh direcionado para ela. Raciocínio vence uma lista fixa.
Para cada achado no inventário, decida em qual balde ele se encaixa usando references/safety-invariants.md e references/auto-fix-categories.md como referência. Capture a justificativa junto a cada entrada — no momento da pré-visualização o usuário vê seu raciocínio, não apenas o veredito. É assim que a confiança é construída.
Escreva findings.json (seu bloco de rascunho — usado nas Fases 4 e 8).
Para diretórios 🟡 (especialmente ~/Downloads, ~/Desktop), faça glob para padrões em references/sensitive-patterns.md. Cruze correspondências com regras salvas downloads-keep / desktop-keep:
- Correspondência em regras salvas → manter silenciosamente (ainda registre em findings)
- Nova correspondência → AskUserQuestion: Manter / Deletar. A resposta se torna uma regra salva para a próxima execução.
Heurística: se um nome de arquivo parece pessoal (jurídico, médico, financeiro, identidade) mas não corresponde a um padrão, pergunte de qualquer forma. Melhor perguntar demais uma vez do que destruir algo insubstituível.
Mostre o plano completo: cada 🟢, cada grupo 🟡 com justificativa, cada recusa 🔴 com motivo. Estime a recuperação total. O usuário implicitamente aprova ao interagir com os portões da Fase 6; eles também podem abortar aqui ("espera, por que X está em verde?").
Execute os itens verdes. Ordene-os do menos invasivo primeiro (varreduras de arquivos pequenos → purgas de cache → limpezas gerenciadas por ferramentas como brew autoremove e pnpm store prune). Capture tamanhos antes/depois para o relatório de delta. Se um falhar, registre e continue — itens verdes são independentes.
Permissão negada (ex.: Chrome segura cache do Perfil 5 enquanto em execução) — registre e siga em frente. Não lute contra isso.
Para cada grupo 🟡, UM AskUserQuestion com Aprovar / Modificar / Pular. Agrupe itens similares (todas versões antigas de runtime em uma pergunta, não uma por versão).
Manuseio especial, quando relevante:
- Downloads com lista de itens a manter —
bash scripts/keeplist-protect.sh ~/Downloads <keepers...>(mover keepers para /tmp, deletar conteúdo, restaurar). Mostre a lista de itens a manter antes de executar para que o usuário possa alterar. - Runtimes antigos — Execute
bash scripts/detect-runtimes.shprimeiro para ver quais versões de Node/Python os projetos realmente usam. Recomende deleção de versões não em uso ativo; salve versões ativas nas regras salvas. - Snapshots APFS —
sudo tmutil thinlocalsnapshots / 21474836480 4recupera ~20 GB com urgência 4. Informe que precisa de sudo. - Mensagens/Anexos — Feche Mensagens primeiro (
osascript -e 'tell application "Messages" to quit'; sleep 3), entãofind ~/Library/Messages/Attachments -mindepth 1 -delete(preservachat.db). - Xcode
DerivedData(se presente) — Seguro deletar; única penalidade é um próximo build mais lento.
Itens pulados são adiados para a próxima execução — anote-os em state.md para que reapareçam.
Resumo limpo: antes/depois df -h, tabela de espaço liberado por categoria, estado de swap de sysctl vm.swapusage. Mencione swap como informacional — "reinicialize para recuperar ~X GB de swap se quiser" — não peça reinicialização (decisão do usuário).
Verificação de sanidade do tamanho da Lixeira — se cresceu na mesma proporção do que deletamos, algo foi transferido em vez de recuperado. Informe isso.
Acrescente uma entrada de execução conforme o formato no cabeçalho de state.md. Atualize Regras Salvas com qualquer coisa aprendida nesta execução (novos runtimes ativos, novas decisões de arquivos sensíveis). Role a entrada mais antiga para a seção compactada se houver mais de 5 entradas completas.
Ao propor uma nova regra salva, confirme com o usuário — não adicione automaticamente. As regras são duráveis; melhor perguntar uma vez.
Marque checkpoint COMPLETED.
<saved_rules_format>
Armazenado na seção "Saved Rules" de state.md. Apresentado em toda execução futura.
Formato: - {tópico}: {regra} — definida em {YYYY-MM-DD ET}
Tópicos que emergem naturalmente (não exaustivos — invente novos quando padrões se repetirem):
downloads-keep,desktop-keep— listas de itens a manter por diretórioactive-node,active-python— versões de runtime em uso realactive-projects— diretórios de projeto a nunca tocarsafe-cache-clear-paths— caminhos automáticos confirmados como seguros*-policy— preferências comportamentais pontuais (ex.:swap-policy,threshold-policy) </saved_rules_format>
<recovery_protocol>
Se state.md mostrar status: IN_PROGRESS:
| Último checkpoint | Retomar em |
|---|---|
| INITIALIZED | Fase 1 |
| INVENTORIED | Fase 2 |
| CATEGORIZED | Fase 3 |
| SENSITIVE_SCANNED | Fase 4 |
| PREVIEWED | Fase 5 |
| GREEN_EXECUTED | Fase 6 |
| YELLOW_RESOLVED | Fase 7 |
| REPORTED | Fase 8 |
Pergunte ao usuário: Retomar / Começar do zero / Mostrar histórico completo. Ao retomar, acrescente à entrada existente; NÃO crie uma nova.
Execute df -h novamente antes de retomar — se o estado do disco mudou materialmente desde a interrupção, re-pergunte.
</recovery_protocol>
<error_handling> Padrão: registre o erro específico, pule o item problemático, continue com o resto. Limpeza de disco é reentrante de forma independente por item.
Aborte a execução apenas se:
- O script de varredura falhou completamente (
findings.jsonestaria incorreto) - Um caminho 🔴 foi quase tocado (bug na categorização → abortar + investigar)
- O usuário disse parar
Para todo o resto (permissão negada única, bloqueio do brew, ferramenta não instalada) — continue e relate no final.
Se o disponível cair abaixo de 500 MiB DURANTE a execução (paradoxal mas possível no meio da categorização em um disco quase cheio), pause a Fase 5, esvazie a Lixeira, depois retome. findings.json vive no mesmo volume que todo o resto.
</error_handling>
<success_criteria>
state.mdtem nova entrada comstatus: COMPLETEDdf -hmostra delta positivo não nulo em Disponível- Nenhum caminho 🔴 foi tocado
- Correspondências sensíveis foram mantidas (com regra salva) ou explicitamente deletadas pelo usuário
- O usuário viu um relatório de delta
- Tamanho da Lixeira verificado (nenhuma transferência mascarando recuperação) </success_criteria>
Ações diretas
Pule a varredura completa quando estas forem claramente a intenção:
- "Só esvaziar a lixeira" → confirme tamanho,
rm -rf ~/.Trash/*após S/N - "Só limpar caches" → execute apenas Fase 5
- "Simular / mostrar o que seria deletado" → Fases 1–4, pare antes da Fase 5
- "O que a última execução fez?" → exiba a entrada mais recente de
state.md - "Adicionar
<caminho>a nunca tocar" / "esquecer lista de itens a manter para<arquivo>" → edite Regras Salvas - "Agendar semanalmente" → ofereça rotina
/schedule; se aceito, proponha adicionar entrada em~/.claude/CLAUDE.md"Automações Ativas de Longa Duração" (não edite automaticamente — proponha para aprovação)
Limites
Ator único ([session]) por enquanto. Promova para multi-ator ([disk-cleanup] para rotina, [session] para manual) quando agendado.
Invocacão manual apenas — nunca acionado automaticamente por outros skills. Arquivo de bloqueio em .lock no diretório do skill previne execuções concorrentes.
Nunca:
sudo rmdiretamente (sudo apenas através de comandos abençoados pela Apple comotmutil)- Modificar
~/.claude/CLAUDE.md(apenas proposto) - Deletar uma correspondência de
references/sensitive-patterns.mdsem confirmação explícita, independentemente de regras salvas - Forçar deleção do
node_modulesde um projeto ativo sem pergunta explícita - Solicitar reinicialização (relate estado de swap apenas)
- Tocar em qualquer coisa em
references/safety-invariants.mdindependentemente de instrução inline do usuário
Limite. Raciocínio é para todos os outros lugares.