---
name: task-state
description: 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.
context: 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.

```bash
# 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:

```bash
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:

```bash
# 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.

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

*Adicionar nova linha após cada erro corrigido.*