harness-retro

Harness retro

Encontre onde as sessões passadas deram errado e mude a configuração para que não aconteça novamente. Cada descoberta deve apontar para evidências em uma transcrição. Nunca aplique uma mudança antes da aprovação do usuário.

1. Minere as transcrições

O minerador é um script apenas com stdlib que está ao lado deste arquivo. Execute-o com -I. Escreva sua saída no scratchpad da sessão, ou em um diretório temporário se não houver:

python3 -I <diretório base desta skill>/scripts/mine.py [CAMINHO] [--since 30d] --out <scratchpad>/retro.json

• Sem CAMINHO, ele minera o projeto para o diretório de trabalho atual. Para minerar um projeto diferente, forneça o caminho do diretório de trabalho, ou use --project=<chave> com o nome da pasta em ~/.claude/projects. Use a forma =, porque as chaves começam com -.
• Use --since se o usuário nomeou uma janela de tempo. Aumente --max-bytes (padrão 40000) somente se a saída for truncada e você precisar de mais.
• Se o usuário perguntar sobre todos os projetos, execute uma vez para cada pasta em ~/.claude/projects e olhe os projetos com mais atrito.

O script imprime um resumo de uma linha. Se ele escaneou poucas ou nenhuma sessão, informe o usuário. Claude Code exclui transcrições após cleanupPeriodDays (padrão 30), então histórico mais antigo pode ter desaparecido. Sugira aumentar essa configuração se quiserem retros mais profundas no futuro.

2. Leia os hits

O JSON lista sessões classificadas por pontuação de atrito. Cada hit tem signal (sinal), score (pontuação), ts (timestamp), prior_prompt (o que o usuário perguntou), recent_actions (as últimas chamadas de ferramenta de Claude antes do hit) e user_reaction ou detail.

Sinais, aproximadamente em ordem de valor:

• user_correction: o usuário contestou. Pontuações de 5 ou mais indicam forte frustração ou repetição ("ainda", "de novo", "eu disse", xingamentos).
• edit_revert e edit_churn: Claude foi e voltou no mesmo arquivo.
• tool_error_streak: Claude continuava batendo na mesma falha.
• interrupted: o usuário parou Claude no meio do turno. Isso geralmente significa que estava indo na direção errada.
• permission_denied: Claude tentou algo que o usuário ou o classificador bloqueou.
• self_retraction: Claude admitiu um erro. Este sinal é ruidoso, então use-o apenas como evidência de apoio.

As regex são grosseiras. Descarte falsos positivos, como "não" em uma instrução normal ou "tente novamente" após um erro de rede. Quando um hit for ambíguo, abra a transcrição ao redor dele. O arquivo é ~/.claude/projects/<chave>/<sessão>.jsonl; use grep para encontrar o timestamp e leia algumas linhas de cada lado. Não leia transcrições inteiras.

3. Agrupe em padrões

Agrupe os hits reais em padrões recorrentes. Um padrão é uma causa raiz, escrita como algo que Claude faz de errado. Exemplos: "Gera novas imagens em vez de usar a biblioteca de assets aprovada", "Edita a versão atual em vez de criar uma nova", "Afirma que uma mudança está visível sem verificar a saída compilada". Para cada padrão, registre:

• Com que frequência aconteceu e em quantas sessões.
• Duas ou três citações curtas do usuário, com título da sessão e data.
• A causa raiz. Escolha uma: conhecimento ausente, uma regra que existia mas foi ignorada, um fluxo de trabalho padrão ruim, verificação ausente ou uma lacuna de ferramenta ou permissão.

Um único incidente conta apenas se o usuário estava claramente irritado ou o custo foi alto, por exemplo, trabalho destrutivo ou perdido.

4. Verifique o harness atual

Antes de propor qualquer coisa, leia o que já está em vigor:

• ~/.claude/CLAUDE.md, mais o CLAUDE.md do projeto e quaisquer aninhados.
• ~/.claude/settings.json, e os .claude/settings.json e .claude/settings.local.json do projeto (hooks, permissões).
• O diretório de memória do projeto ~/.claude/projects/<chave>/memory/ e seu MEMORY.md.
• Skills em ~/.claude/skills/ e as do projeto em .claude/skills/.

Se um padrão já é coberto por uma regra que Claude ignorou, adicionar a mesma regra novamente não vai ajudar. Torne a regra mais específica e coloque-a onde será vista, ou mude para um mecanismo mais forte.

5. Escolha a correção

Para cada padrão, use o mecanismo mais leve que realmente funcionará:

Causa raiz	Correção
Um fato do projeto que Claude não sabia	Um arquivo de memória no diretório de memória do projeto, com frontmatter name, description, metadata.type, um corpo com Por que: e Como aplicar:, e um ponteiro de uma linha em MEMORY.md. Atualize uma memória existente em vez de duplicá-la.
Uma regra permanente para este repositório	CLAUDE.md do projeto
Uma regra para todos os projetos	~/.claude/CLAUDE.md
Uma regra que continua sendo quebrada e pode ser verificada por um script (formatação, strings proibidas, um comando obrigatório antes do commit)	Um hook em settings.json. Use a skill update-config se estiver disponível.
Solicitações ou negações repetidas de permissão para comandos seguros	Proponha entradas de lista de permissões, ou sugira a skill fewer-permission-prompts se estiver disponível. Não amplie permissões para comandos destrutivos.
Um fluxo de trabalho de várias etapas que continua dando errado	Uma skill nova ou editada (use skill-creator se estiver disponível).
Um bug do produto Claude Code	Anote no relatório. Não há correção de harness.

Escreva regras como instruções concretas e verificáveis que nomeiem a coisa específica, como arquivos, caminhos de assets, comandos ou nomes de versão. "Tenha cuidado com imagens" é vago demais para ser acionável.

6. Relate e obtenha aprovação

Apresente uma seção por padrão, começando pelo mais custoso. Cada seção fornece:

1. O padrão, em uma linha.
2. As evidências: contagem, sessões e 2 ou 3 citações curtas com data.
3. A causa raiz.
4. A mudança proposta: o arquivo alvo e o texto exato ou diff.

Depois, pergunte quais mudanças aplicar. Uma pergunta multi-select AskUserQuestion com uma opção por padrão funciona bem. Aplique apenas as mudanças aprovadas e, em seguida, liste o que mudou e onde.

Regras de escrita

Qualquer coisa escrita em CLAUDE.md, memória ou skills deve seguir quaisquer regras de escrita nos próprios arquivos CLAUDE.md do usuário, como tom, palavras proibidas ou regras de atribuição. Mantenha curto e específico. Citações de transcrições podem incluir segredos que o usuário colou. O minerador oculta formatos comuns de chaves, mas verifique antes de copiar texto para qualquer arquivo.