Lição 12 de 13: Quando o /work trava

Por que o /work trava (e por que você não precisa lutar contra)

Durante a fatia 1, é provável que o /work tenha travado em algum momento. Pode ter sido (a) ele propondo algo confuso que você não entende, (b) ele refazendo a mesma proposta com pequena variação sem chegar lugar nenhum, ou (c) ele pulando uma tarefa que estava ali no plano.

Cada um desses tem cura específica. Esta lição registra o playbook num arquivo de docs pra você consultar quando travar de novo. E vai travar de novo: faz parte do trabalho.

Antes de qualquer coisa: rebobine a fatia

Quando uma fatia desanda, o primeiro gesto não é git reset nem editar arquivo na mão. É rebobinar pro estado anterior à confusão. O Claude Code mantém um checkpoint do estado do código antes de cada mudança que ele faz, e você volta pra um deles apertando Esc duas vezes ou rodando /rewind. Ao rebobinar, você escolhe restaurar o código, a conversa, ou os dois. Isso ajuda quando a sessão entrou num caminho mental ruim e você quer limpar tanto o que foi escrito quanto o histórico que levou até ali.

Use isso como passo zero: rebobinou, você está de volta num ponto bom e propõe de novo com um prompt melhor, sem carregar o lixo das tentativas que falharam.

Os 3 padrões de travamento

Padrão 1 — Proposta confusa

Sintoma: Claude propõe algo, você lê 3 vezes, ainda não entende o que ele vai fazer. Os arquivos mencionados podem nem existir; a sequência das operações não bate; faltam passos.

Causa típica: o plano está vago num ponto específico. Claude tentou interpretar a Task list e caiu numa região ambígua.

Gesto de cura: pergunta específica, não geral. Não pergunte "você pode ser mais claro?", porque isso gera nova proposta igualmente confusa. Pergunte "em que arquivo exato você vai modificar?" ou "qual função/lib você está usando aqui?". Isso força o Claude a decompor.

Antes de prosseguir, lista pra mim, em formato bullet:

1. Quais arquivos você vai modificar (paths exatos)
2. Qual função/lib você está usando em cada modificação
3. Como você sabe que essa é a função certa (link pra docs, ou referência no projeto)

A resposta vai revelar onde a confusão mora. Geralmente a resposta do item 3 expõe que o Claude está chutando. Aí você decide se a função existe (com check de package.json da L01) ou pede alternativa.

Padrão 2 — Refazendo sem parar

Sintoma: Claude propõe X. Você rejeita. Ele propõe X' (variação). Você rejeita. Ele propõe X''. Você sente que está dando voltas. Ninguém está convergindo.

Cenário real: você pede "API route que insere recibo." Claude propõe usar try/catch global. Você rejeita ("sem defensive try/catch"). Ele propõe try/catch ao redor do insert apenas. Você rejeita ("não trata os 3 erros específicos"). Ele propõe try/catch + tratamento de unique constraint. Você rejeita ("falta foreign key"). Ele adiciona FK. Você rejeita ("e o connection error?"). Cada variação trata um pedaço, nenhuma cobre o conjunto. Você não definiu o conjunto no plano. Esse é o sinal.

Causa típica: ou a tarefa do plano não está clara o suficiente, ou Claude está preso num caminho mental que não bate com o que você quer. Continuar refazendo nessa sessão é gastar token sem resultado.

Gesto de cura: pare. Sai da sessão, lê o plano, identifica o que está faltando ou ambíguo. Volta com um plano refinado, não com mais aprovações/rejeições.

Para tudo. Vamos rever o plano.

Re-leia a Task list do plano ativo. A tarefa que estamos tentando é a número [N: <descrição>].

Antes de propor de novo, me responde:
1. O que você acha que essa tarefa pede?
2. Onde no plano você está vendo a especificação?
3. Que decisão ainda está ambígua que você precisaria que eu definisse?

Se a resposta da 3 listar 2+ ambiguidades, vamos parar e atualizar o plano antes de tentar de novo.

Muito provavelmente a resposta vai listar 1-2 ambiguidades reais. Você atualiza o plano (Acceptance criteria, ou move pra Out of scope), faz commit do plano, e roda /work de novo. Aí costuma fluir.

Padrão 3 — Pulando tarefa

Sintoma: Você roda /work, espera que ele pegue a tarefa N (a próxima pendente), mas ele pega a N+2 ou propõe algo que não está no plano. Você confere o git log: a tarefa N não foi commitada.

Causa típica: a heurística de cruzamento entre Task list e git log (que você viu na L01) errou. Pode ter sido: títulos das tarefas no plano vagos demais pra match; commits anteriores com mensagem que parecia cobrir a tarefa; refatoração do plano.

Gesto de cura: seja explícito sobre qual tarefa quer.

Pula essa proposta. Quero trabalhar especificamente na tarefa N do plano, que diz: "<texto exato copiado da Task list>".

Confirma que entendeu a tarefa, e propõe a execução apenas dela. Ignora outras por agora.

Isso resolve no curto prazo. No longo prazo, a causa raiz é o plano: ou os títulos das tarefas precisam ser mais específicos, ou a tarefa N já foi feita parcialmente e o plano não foi atualizado. Anota como aprendizado pro próximo plano (docs/lessons-learned.md da L10).

Passo 1 — Documente o playbook no repo

Cria o arquivo docs/stuck-mode-playbook.md com 3 padrões de travamento do /work, cada um com sintoma, causa, e gesto de cura. Usa exatamente os 3 padrões da L12 do Módulo 3 do Builder OS:

## Padrão 1 — Proposta confusa
Sintoma: ...
Causa: ...
Gesto: pergunta de decomposição (arquivos exatos, funções exatas, fonte da função).

## Padrão 2 — Refazendo sem parar
Sintoma: ...
Causa: ...
Gesto: parar, revisar plano, refazer plano se preciso, antes de tentar de novo.

## Padrão 3 — Pulando tarefa
Sintoma: ...
Causa: ...
Gesto: ser explícito sobre tarefa, copiar texto exato do plano.

Mostre o diff antes de criar.

Passo 2 — Faça o commit

Faça commit do docs/stuck-mode-playbook.md com mensagem: docs: stuck-mode playbook

Build Diary — segmente o diagnóstico antes de agregar

O CEAP tem o "Paradoxo do Sóstenes" registrado em NOTAS_DO_AUTOR.md: score agregado escondeu anomalia segmentada. A regra mais geral:

Análises agregadas mascaram anomalias específicas. Sempre segmente por categoria antes de concluir.

Aplicado ao /work travado: "proposta confusa" agregado esconde qual parte da proposta é confusa. Quando você pergunta "você pode ser mais claro?" (agregado), Claude responde com nova proposta agregada. Quando você pergunta "em que arquivo exato você vai modificar?" (segmentado), a resposta revela onde a confusão mora: geralmente um arquivo específico que ele estava chutando.

A regra: quando o problema está agregado demais, segmente antes de diagnosticar. Vale pra /work e pra debugar produção. Quando travar, a primeira pergunta é "agregado demais? consigo segmentar?"

Takeaways

• 3 padrões de travamento, 3 gestos: confusa → decompõe arquivo por arquivo; refazendo → para e revisa plano; pulando → seja explícito sobre qual tarefa.
• Não pergunte "pode ser mais claro?", que gera proposta igualmente vaga. Pergunte arquivo/função/fonte (segmentado).
• Se você está rejeitando variação após variação, o problema é o plano, não o Claude. Sai da sessão, refina o plano, volta.
• Playbook commitado vira referência. Próxima vez que travar, abre docs/stuck-mode-playbook.md, diagnostica em 1 min.

Você terminou quando

Três coisas:

1. docs/stuck-mode-playbook.md commitado com os 3 padrões
2. Você consegue, num travamento futuro, identificar de qual dos 3 é o caso
3. Tem 1 prompt copiável pra cada padrão pronto no playbook