claude-plugins/gestao/skills/task-state/SKILL.md

name, description, context

name	description	context
task-state	Gestão de estado persistente de tarefas entre sessões. Cria, actualiza e lê .task-state.md para tarefas complexas. Usar quando tarefa tem >2 sessões, múltiplos ficheiros, ou risco de perder contexto por compaction.	fork

/task-state — Gestão de Estado de Tarefa

Persiste decisões, ficheiros e checkpoints entre sessões. Sobrevive a context compaction.

---

Quando usar

Usar quando:

• Tarefa com >1 sessão de trabalho
• Múltiplos ficheiros a modificar (>3)
• Risco de context compaction apagar contexto crítico
• Tarefas que requerem aprovação por checkpoint

Não usar quando:

• Tarefas de <30 minutos
• Edições simples de 1-2 ficheiros
• Respostas a perguntas

---

Comandos

/task-state init

Cria .task-state.md no directório actual baseado no template.

# Verificar se já existe
[ -f ".task-state.md" ] && echo "AVISO: já existe — usar /task-state update" && exit 1

# Copiar template
cp ~/.claude-work/task-state-template.md .task-state.md
echo "Criado: .task-state.md"

Após criar, preencher os campos de Identificação manualmente.

/task-state read

Lê e apresenta o estado actual — útil ao retomar uma tarefa interrompida:

cat .task-state.md

Ao retomar: ler "Próximo passo imediato" e "Bloqueantes actuais" primeiro.

/task-state checkpoint N

Marca checkpoint N como concluído:

# Exemplo: marcar checkpoint 2 como feito
sed -i "s/- \[ \] Sub-issue 2:/- [x] Sub-issue 2:/" .task-state.md

/task-state update

Actualizar campos específicos ao longo do trabalho:

• Adicionar ficheiros modificados à lista
• Registar decisões tomadas
• Actualizar "Próximo passo imediato"
• Adicionar bloqueantes encontrados

---

Padrão Vertical Plans

Diferença para planos monolíticos:

Monolítico	Vertical Plans
Lê o plano completo	Divide em sub-issues com checkpoint
Implementa tudo	Implementa 1 sub-issue
Verifica no final	Testa + valida antes de avançar
Falha tarde	Falha cedo e barato

Regra: Nunca avançar para sub-issue N+1 sem N estar testado e marcado.

---

Integração com writing-plans

1. /writing-plans → cria plano com sub-issues e critérios de sucesso
2. /task-state init <nome> → cria ficheiro de estado
3. A cada sub-issue: implementar → testar → /task-state checkpoint N → commit
4. Se sessão interromper: ler .task-state.md → continuar no "Próximo passo imediato"

---

Template

O template está em ~/.claude-work/task-state-template.md. Actualizar o template para reflectir necessidades do projecto actual.

---

Contexto crítico — o que documentar

Documentar TUDO que está só na cabeça do Emanuel e que o agente precisa:

• "Este servidor é produção — não tocar sem aprovação"
• "O cliente X é sensível a preços — nunca mencionar concorrentes"
• "A BD usa UTF-8 mas tem registos ISO-8859 antigos — cuidado com migrações"

Fonte: Regra #361 — agente apagou BD de produção porque "é live" estava só na cabeça do humano.

---

Healing Log

Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar.

{"date":"","issue":"","fix":"","source":"user|auto"}

Adicionar nova linha após cada erro corrigido.