espaço-de-trabalho-causal-externo

Habilidade de Espaço de Trabalho Causal Externo

Propósito

Esta habilidade transforma um agente de terminal em um sistema de raciocínio com um espaço de trabalho externo e inspecionável.

O agente não deve se comportar como um simples gerador de texto quando a tarefa for complexa. Ele deve construir e manipular um modelo local do problema antes de produzir conclusões, planos, patches ou recomendações.

O objetivo é aproximar, por meio do uso de ferramentas e estado explícito, um modelo de mundo externo temporário composto por objetos, relações, restrições, causalidades, invariantes, hipóteses concorrentes, testes, evidências de verificação, decisões e incertezas residuais.

Isto não é um espaço latente neural. É um substituto prático baseado em disco: um espaço de trabalho cognitivo externo que pode ser lido, atualizado, verificado, compartilhado e auditado.

Quando Usar Esta Habilidade

Use esta habilidade para tarefas complexas ou de alto impacto, especialmente:

• análise de arquitetura;
• depuração;
• análise de causa raiz;
• refatoração;
• alterações em vários arquivos;
• requisitos pouco claros ou instáveis;
• decisões técnicas estratégicas;
• análise causal;
• trabalho sensível a desempenho;
• trabalho sensível a segurança;
• tarefas com múltiplas explicações plausíveis;
• tarefas onde uma resposta errada pode criar dívida técnica futura;
• tarefas onde verificação, rastreabilidade ou falseabilidade são importantes.

Não use esta habilidade intensamente para:

• perguntas triviais;
• pequenas edições isoladas;
• formatação simples;
• respostas factuais diretas que não dependem da realidade local do projeto;
• tarefas onde um espaço de trabalho completo adicionaria mais ruído do que valor.

Se a tarefa for simples, responda diretamente e explique brevemente que a habilidade não foi necessária.

Espaço de Trabalho Alvo

O espaço de trabalho ativo é o diretório a partir do qual o agente é iniciado, ou a raiz do projeto identificada explicitamente pelo usuário.

O espaço de trabalho causal pertence ao projeto alvo, não ao diretório da habilidade.

Use:

<raiz-do-projeto>/.agent/current/

O diretório da habilidade contém o protocolo. O diretório do projeto contém o estado da tarefa.

O agente não deve escrever estado de raciocínio específico da tarefa no próprio pacote da habilidade.

Inspeção do Espaço de Trabalho Atual

Antes de agir em qualquer tarefa específica de repositório ou ambiente, inspecione apenas o necessário do espaço de trabalho atual.

Identifique quando relevante:

• a estrutura do projeto;
• arquivos e pastas relevantes;
• documentação disponível;
• comandos de build, teste e validação;
• restrições impostas pela arquitetura existente;
• qualquer AGENTS.md, arquivo de substituição, arquivo de instrução local ou orientação específica da tarefa;
• se .agent/current/ já existe.

O agente não deve assumir a arquitetura de memória quando a tarefa depende da realidade local do projeto.

Semântica de Execução Nova

No início de cada nova tarefa que usa esta habilidade, redefina .agent/current/ no projeto alvo.

Regras:

• Se .agent/ não existir, crie-o.
• Se .agent/current/ não existir, crie-o.
• Se .agent/current/ já existir de uma tarefa anterior, exclua ou sobrescreva seu conteúdo anterior antes de iniciar a nova tarefa.
• Não exclua .agent/notes/, .agent/reports/, .agent/tmp/ ou .agent/archive/ a menos que o usuário peça explicitamente.
• Não preserve o estado histórico por padrão.
• Se o usuário pedir explicitamente para preservar o histórico, copie o .agent/current/ anterior para .agent/archive/<timestamp-ou-nome-da-tarefa>/ antes de redefini-lo.

O propósito de .agent/current/ é representar apenas a tarefa atual. Ele não deve acumular silenciosamente raciocínio desatualizado de prompts anteriores.

Propriedade do Espaço de Trabalho

Para uma determinada tarefa, .agent/current/ deve ter um único escritor.

Crie ou sobrescreva:

.agent/current/owner.md

owner.md deve declarar:

• nome da tarefa ou objetivo curto;
• agente ou função proprietária, se conhecido;
• hora de início se disponível;
• status: ativo, concluído, parcial, bloqueado ou abandonado;
• se o espaço de trabalho foi redefinido recentemente.

Se outro proprietário ativo for detectado e o usuário não iniciou explicitamente uma nova tarefa, não sobrescreva silenciosamente. Trate o espaço de trabalho como somente leitura ou declare que uma nova execução requer a redefinição de .agent/current/.

Arquivos Obrigatórios em Disco

Para cada tarefa complexa, ambígua, arquitetural, de depuração, refatoração, estratégica, causal ou de alto impacto, crie ou atualize pelo menos:

.agent/current/owner.md
.agent/current/task.md
.agent/current/world.md
.agent/current/hypotheses.md
.agent/current/claims.md
.agent/current/verification.md
.agent/current/decision.md

Esses arquivos não são decoração. Eles são a memória de trabalho externa do agente.

O agente deve lê-los e atualizá-los durante a tarefa. A resposta final deve ser consistente com .agent/current/decision.md e com os status de alegação retidos em .agent/current/claims.md. Antes da resposta final, .agent/current/owner.md não deve mais estar ativo.

Funções dos Arquivos Obrigatórios

owner.md

Identifica a execução atual e evita sobrescrita acidental por outra tarefa ou agente.

Deve incluir:

• tarefa atual;
• proprietário;
• modo: direto, delegado, exploratório, diagnóstico ou suporte à implementação;
• status;
• decisão de redefinição.

task.md

Define o limite da tarefa.

Deve incluir:

• objetivo do usuário;
• objetivo interpretado;
• escopo;
• fora do escopo;
• restrições;
• critérios de sucesso;
• proibições explícitas do usuário;
• suposições que ainda requerem verificação.

world.md

Constrói o modelo local do problema.

Deve incluir:

• objetos: componentes, arquivos, serviços, atores, conceitos, estruturas de dados;
• relações: dependências, propriedade, fluxo de dados, fluxo de chamadas, ciclo de vida, sequência temporal;
• restrições: técnicas, funcionais, de segurança, arquiteturais, de desempenho, de compatibilidade;
• causalidades: o que produz o quê, o que quebra o quê, o que depende do quê;
• invariantes: o que deve permanecer verdadeiro após a intervenção;
• zonas de incerteza: fatos ainda não verificados.

hypotheses.md

Previne o raciocínio de hipótese única.

Deve incluir explicações concorrentes ou caminhos de solução:

| Hipótese | Suporta | Contradiz | Teste de falseabilidade | Status |
|---|---|---|---|---|
| H1 | ... | ... | ... | retida/rejeitada/suspensa |
| H2 | ... | ... | ... | retida/rejeitada/suspensa |

As hipóteses devem ser rejeitadas, retidas ou suspensas explicitamente.

claims.md

Previne confusão de regime de verdade.

Deve listar as afirmações importantes que afetam materialmente a tarefa, digitadas e com status:

| ID | Alegação | Tipo | Fonte / Evidência | Status | Impacto | Notas |
|---|---|---|---|---|---|---|
| C-001 | ... | fato / inferência / hipótese / restrição / invariante / risco / valor / decisão | arquivo, comando, declaração do usuário, resultado de ferramenta, raciocínio | verificado / inferido / plausível / suspenso / rejeitado / não-verificado | baixo / médio / alto / crítico | ... |

Regras:

• fato requer uma âncora de evidência.
• inferência deve nomear os fatos dos quais depende.
• hipótese deve permanecer distinguível de fato até ser falseada ou retida.
• valor pode guiar julgamento, mas não deve se passar por prova empírica.
• decisão deve ser suportada por alegações retidas e não deve depender silenciosamente de alegações rejeitadas.

Use apenas alegações materialmente importantes. Não transforme o espaço de trabalho em um despejo de alegações prolixo.

verification.md

Previne verificação falsa.

Deve incluir:

• comandos realmente executados;
• arquivos realmente inspecionados;
• saídas ou observações importantes;
• verificações aprovadas, falhas, ignoradas ou não executadas;
• limites de verificação;
• por que qualquer verificação mais forte era impossível ou foi intencionalmente ignorada.

Uma alegação de verificação é válida apenas quando tem uma âncora de evidência: um comando, arquivo inspecionado, saída observada, resultado de ferramenta ou razão explícita pela qual a verificação não pôde ser realizada.

decision.md

Estabiliza a conclusão antes da resposta final.

Deve incluir:

• modelo retido;
• caminhos rejeitados;
• ação recomendada;
• próximo passo mínimo seguro;
• riscos;
• status de verificação;
• incerteza restante;
• se a implementação é permitida ou deve esperar.

Princípio Operacional Central

Para cada tarefa complexa, primeiro construa um modelo local do problema.

O modelo deve incluir:

• objetos;
• relações;
• restrições;
• causalidades;
• invariantes;
• hipóteses concorrentes;
• zonas de incerteza;
• oportunidades de verificação;
• tipos e status de alegações para afirmações importantes.

Em seguida, teste as hipóteses por:

• inversão;
• contradição;
• casos limite;
• verificações de absurdo;
• verificações de mecanismo causal;
• verificação executável sempre que possível e seguro.

Somente após essa estabilização o agente pode produzir uma resposta, plano, patch ou recomendação.

Referências Obrigatórias

Quando esta habilidade for usada, siga estes arquivos de protocolo do pacote da habilidade quando relevante:

• references/world-model-workspace.md: como construir e manter o modelo local externo.
• references/structural-reasoning-protocol.md: raciocínio baseado em invariantes, inversão, contradição, teste de absurdo e redução de entropia.
• references/tool-verification-protocol.md: como usar ferramentas, testes, scripts e comandos de terminal como cognição externa.
• references/claims-ledger-protocol.md: como separar fatos, hipóteses, inferências, valores, riscos e decisões.
• references/state-and-memory-protocol.md: como persistir o estado de trabalho sem poluir o projeto.
• references/final-response-contract.md: como relatar conclusões, alterações, limites e incertezas residuais.

Os arquivos de protocolo fazem parte da habilidade. Os arquivos .agent/current/ fazem parte do espaço de trabalho do projeto alvo.

Loop de Execução Padrão

Para tarefas complexas, use este loop:

1. Identifique o objetivo real e se esta habilidade é necessária.
2. Inspecione o espaço de trabalho apenas o necessário.
3. Redefina ou crie .agent/current/ para a nova tarefa.
4. Crie owner.md, task.md, world.md, hypotheses.md, claims.md, verification.md e decision.md.
5. Construa um modelo local do problema.
6. Identifique invariantes e restrições.
7. Registre fatos, restrições, invariantes, hipóteses, riscos, valores e decisões materialmente importantes em claims.md.
8. Gere hipóteses concorrentes ou caminhos de solução.
9. Teste-as logicamente e, quando possível, com ferramentas.
10. Registre evidências e verificação ignorada em verification.md, e atualize os status de alegação afetados em claims.md.
11. Elimine hipóteses instáveis.
12. Esboce a conclusão retida em decision.md a partir apenas de alegações retidas.
13. Aja apenas dentro do escopo validado, se a ação for permitida.
14. Verifique o resultado, se uma alteração foi feita.
15. Finalize decision.md.
16. Atualize o status de owner.md para concluído, parcial, bloqueado ou abandonado.
17. Realize a Porta de Integridade Final do Espaço de Trabalho.
18. Só então produza a resposta final.

Regras de Comportamento

• Prefira estrutura à improvisação.
• Prefira fatos verificados a suposições fluentes.
• Prefira alterações mínimas e reversíveis a edições especulativas amplas.
• Não modifique arquivos não relacionados.
• Não esconda incerteza.
• Não afirme que testes passaram a menos que tenham sido realmente executados.
• Não use palavras como verificado, validado, confirmado, testado, aprovado, falhou, inspecionado ou verificado a menos que a alegação esteja vinculada a uma âncora de evidência.
• Se baseado em leitura estática, diga "inferido de" e nomeie os arquivos inspecionados.
• Não infira convenções do projeto quando elas podem ser inspecionadas.
• Não deixe conteúdo desatualizado de .agent/current/ influenciar uma nova tarefa após a redefinição.
• Não deixe suposições não tipadas entrarem na resposta final quando afetarem materialmente a conclusão.
• Se a tarefa for simples, evite engenharia excessiva do processo de raciocínio.

Uso de Ferramentas e Verificação

Uma resposta apenas linguística é aceitável para discussão conceitual.

Para implementação, depuração, validação de arquitetura, alegações específicas de repositório ou alegações específicas de ambiente, prefira:

• ler arquivos;
• pesquisar símbolos;
• inspecionar configuração;
• executar testes;
• executar verificações de tipo;
• executar linters;
• gerar diffs;
• usar scripts pequenos;
• criar verificações reproduzíveis.

Use a verificação razoável mais forte disponível sem violar as restrições do usuário.

Se um comando for destrutivo, com impacto na produção, caro ou explicitamente proibido, não o execute. Registre a verificação ignorada e o motivo em verification.md.

Porta de Integridade Final do Espaço de Trabalho

Antes de escrever a resposta final, o agente DEVE realizar uma porta de integridade final do espaço de trabalho.

Esta porta é obrigatória sempre que .agent/current/ foi criado.

O agente deve reabrir ou re-verificar:

• .agent/current/owner.md
• .agent/current/task.md
• .agent/current/world.md
• .agent/current/hypotheses.md
• .agent/current/claims.md
• .agent/current/verification.md
• .agent/current/decision.md

A resposta final não é permitida até que:

1. todos os arquivos obrigatórios existam;
2. .agent/current/owner.md não contenha mais status: ativo;
3. o status seja um de:
   • concluído
   • parcial
   • bloqueado
   • abandonado
4. .agent/current/decision.md contenha a conclusão retida;
5. .agent/current/verification.md declare o modo de verificação;
6. o rastro final do espaço de trabalho mencione apenas arquivos que realmente existem.

Se a tarefa chegou a uma conclusão utilizável, use:

status: concluído

Se a tarefa produziu análise útil mas a verificação está incompleta, use:

status: parcial

Se informações obrigatórias estão faltando, use:

status: bloqueado

O agente DEVE atualizar owner.md como a última escrita no espaço de trabalho antes da resposta final.

Nunca deixe owner.md com status: ativo após produzir a resposta final.

Expectativas de Saída

A resposta final deve ser concisa mas completa. Deve ser derivada de .agent/current/decision.md.

Deve incluir, quando relevante:

• o que foi compreendido;
• o que foi inspecionado;
• qual modelo ou visão foi adotado;
• qual(is) hipótese(s) foram excluídas e por quê;
• qual ação foi tomada ou recomendada;
• qual o próximo passo mínimo seguro;
• quais verificações foram executadas e com quais resultados;
• quais verificações foram ignoradas e por quê;
• quais riscos ou incertezas permanecem;
• que a resposta é derivada do espaço de trabalho causal externo.

Use estruturas como:

• "Com base na análise documentada em .agent/current/decision.md..."
• "A hipótese H2 foi rejeitada porque os comandos de verificação em .agent/current/verification.md mostraram que..."
• "Uma zona de incerteza permanece: o comportamento de X em Y ainda não foi observado, conforme registrado em .agent/current/world.md."