jhincapie/egm-cursor

Relatório de Deriva EGM: o que o documento dizia versus o que foi construído

/egm-implement constrói a partir do documento de design e registra a deriva em IMPLEMENT.md conforme ela ocorre. Alguma deriva ainda escapa: uma alteração que a sessão julgou pequena demais para registrar, uma correção posterior, uma interface que se estabeleceu de forma diferente quando surgiram chamadores reais. Esta skill mede a lacuna após o fato e a documenta, para que o usuário possa posteriormente dizer "atualize o documento de design para corresponder" e o documento volte a ser a fonte da verdade.

Invocar como /egm-drift-report [caminho-para-documento-de-design].

Reflexos operacionais do EGM (preâmbulo compartilhado)

Toda skill neste conjunto carrega estes quatro reflexos, porque nem toda superfície carrega um CLAUDE.md global. Eles vêm do artigo Elephant-Goldfish e se aplicam a toda a sessão, não apenas enquanto esta skill é executada.

1. Design é o novo código. Para qualquer funcionalidade ou alteração não trivial, desenvolva um documento de design antes de escrever código. Se o design não for claro o suficiente para que o código se escreva sozinho, projete primeiro (/egm-design).
2. Recuse a bajulação. Seu trabalho é desafiar o pensamento do usuário; concordar por si só não ajuda. Se você estiver prestes a dizer "ótimo ponto" ou "você está absolutamente certo", pare e procure o que está errado. Se o usuário disser "Você não está sendo útil" (o reset do EGM), trate como um sinal de que você concordou demais e volte a encontrar falhas.
3. IA propõe primeiro. Nunca deixe o usuário semear um design, framework ou rubrica com seu próprio rascunho inicial. Você propõe primeiro, em prosa e diagramas de blocos; o usuário reage e argumenta.
4. Salve os artefatos. Persista a tríplice descrição + critérios + saída de forma durável: docs/designs/<slug>.md, os ledgers em docs/egm/<slug>/, PEANUTS.md na raiz do código-fonte, e a tríplice /egm-decide em seu local mapeado na superfície onde essa skill está instalada. A transcrição do chat não é o artefato.

Regras rígidas: não quebre estas

1. Somente leitura. O único arquivo que esta skill escreve é docs/egm/<slug>/DRIFT-REPORT.md. Nunca edite o documento de design, o código, os testes ou qualquer outro ledger (IMPLEMENT.md, GOLDFISH.md, ELEPHANT.md). Aplicar as atualizações sugeridas é uma solicitação separada que o usuário faz posteriormente.
2. Evidência ou não é deriva. Cada item cita o que o documento diz (seção e uma breve citação) e o que foi construído (caminho:linha, ou um commit, ou "arquivo inexistente"). Um item sem evidência em ambos os lados é uma questão em aberto, listada como tal.
3. O código é o fato observado; o documento é a alegação. Relate a diferença de forma neutra. Não decida qual lado está certo, a menos que um ledger registre a decisão; a atualização sugerida é uma proposta, não um veredito.
4. Olhos frescos fazem a comparação. A sessão que implementou a funcionalidade é tendenciosa a ler sua própria intenção no código. Passe a comparação para um subagente fresco e somente leitura (Passo 3) sempre que um estiver disponível.

Fluxo de trabalho

Progresso do relatório de deriva EGM:
- [ ] Passo 1: documento de design e slug resolvidos; docs/egm/<slug>/ encontrado
- [ ] Passo 2: commit de base escolhido; caminhos do pacote de evidências listados
- [ ] Passo 3: comparação executada por um subagente fresco e somente leitura (ou inline, anotado)
- [ ] Passo 4: descobertas verificadas, classificadas e escritas em DRIFT-REPORT.md
- [ ] Passo 5: usuário informado de onde está o relatório e que pode solicitar a aplicação das atualizações

Passo 1: Resolver o documento de design

Prefira o argumento do usuário. Caso contrário, procure na pasta nomeada por design_doc_path: no AGENTS.md ou CLAUDE.md do projeto e, senão, em docs/designs/*.md. Se existir exatamente um documento, use-o; se houver vários, liste-os e pergunte qual. O slug é o nome do arquivo do documento sem .md, e o diretório de estado é docs/egm/<slug>/. Se esse diretório não existir, a funcionalidade nunca passou pelo /egm-design; diga isso e ofereça-se para escrever o relatório mesmo assim (criando apenas docs/egm/<slug>/DRIFT-REPORT.md).

Passo 2: Escolher a base e reunir o pacote de evidências

A base é o ponto em que o documento foi aprovado. Escolha a primeira que se aplicar e registre qual você usou:

1. O commit que definiu human_review_gate: passed (ou skipped-solo) em docs/egm/<slug>/GOLDFISH.md: git log --format='%H %ad %s' --date=short -- docs/egm/<slug>/GOLDFISH.md.
2. O último commit que tocou o documento de design em ou antes de start_date em IMPLEMENT.md: git log --format='%H %ad %s' --date=short -- <doc>.
3. Pergunte ao usuário por um commit ou data.

Em seguida, liste, sem resumir, as evidências que a comparação lerá:

• o documento de design (no HEAD e na base, se tiver mudado desde então: git show <base>:<doc>);
• docs/egm/<slug>/IMPLEMENT.md, especialmente ## Arquivos tocados, cada entrada ## Deriva (aberta e resolvida) e ## Verificação;
• notas de disposição do GOLDFISH.md onde registram uma alteração no documento;
• git log --stat <base>..HEAD e git diff --stat <base>..HEAD, mais alterações não commitadas de git status e git diff;
• os arquivos que a Implementação Detalhada do documento enumera e os arquivos que o diff tocou que o documento não menciona.

Não estão no pacote: este chat, o raciocínio de design do ELEPHANT.md ou sua própria lembrança de por que algo foi feito. Estes pertencem à coluna "provável motivo" apenas quando um ledger assim o disser.

Passo 3: Executar a comparação em uma sessão fresca e somente leitura

No Cursor, gere um subagente Task do tipo drift-auditor (instalado em ~/.cursor/agents/drift-auditor.md, readonly: true). Se não estiver instalado, use um subagente Task genérico e diga a ele que é somente leitura. Envie o prompt em assets/drift-auditor-prompt.md com o caminho do documento, slug, base e lista de evidências preenchidos. Não adicione mais nada: nenhum resumo da implementação, nenhuma explicação de por que as coisas mudaram.

Se não existir runtime de subagente, faça a comparação inline seguindo você mesmo o mesmo prompt e registre comparison: inline (no fresh subagent available) no cabeçalho do relatório para que o leitor saiba que não foi independente.

Passo 4: Verificar, classificar e escrever o relatório

Verifique cada item retornado antes de escrevê-lo: abra o caminho:linha citado e a seção citada do documento e descarte ou corrija qualquer coisa que a evidência não suporte. Use as categorias no modelo: changed-approach, added, not-built, renamed-or-moved, interface-change, data-model-change, behavior-change, new-dependency, constraint-discovered, alternative-switched. A gravidade é major (o documento enganaria um leitor sobre como o sistema funciona), minor (um detalhe está errado) ou cosmetic (nomenclatura, redação).

Cruze referências com IMPLEMENT.md: marque cada item como logged (existe uma entrada de deriva, com seu status) ou unlogged. Itens não registrados de gravidade major são o destaque.

Escreva docs/egm/<slug>/DRIFT-REPORT.md a partir de assets/drift-report-template.md. Se o arquivo já existir, coloque o novo relatório datado no topo, sob o cabeçalho do arquivo, e mova os relatórios anteriores para abaixo de ## Relatórios anteriores, sem alterações. Nunca reescreva um relatório anterior.

Se não houver deriva, escreva o relatório mesmo assim com drift_items: 0, a base usada e o que foi comparado, para que "sem deriva" seja um resultado registrado, e não uma ausência.

Passo 5: Devolver ao usuário

Informe o usuário, neste formato:

Relatório de deriva escrito em docs/egm/<slug>/DRIFT-REPORT.md: itens ( principais, não registrados em IMPLEMENT.md). Não alterei o documento de design nem o código. Quando quiser que o documento corresponda ao que foi construído, peça-me para aplicar as atualizações sugeridas do relatório; itens que alteram o Plano Técnico devem passar novamente pelo /egm-design, e uma reescrita grande pelo /egm-review.

Não aplique as atualizações nesta sessão, a menos que o usuário peça depois de ver o relatório.

Antipadrões

• Corrigir o documento enquanto relata. O relatório é a entrega. Editar o documento mistura medição com mudança e esconde qual foi a deriva.
• Corrigir o código para corresponder ao documento. Mesmo problema na outra direção. O usuário decide qual lado se move.
• Explicar a deriva de memória. "Mudamos isso porque X" sem uma linha de ledger é um palpite; escreva reason: unknown e deixe o usuário preencher.
• Resumir o diff em vez de comparar. Uma lista de arquivos alterados não é um relatório de deriva. Cada item vincula uma alegação do documento a um fato observado.
• Pular a sessão fresca para economizar tempo. A sessão implementadora já acredita que o código corresponde ao documento. Essa crença é o que esta skill existe para testar.

Onde esta skill se encaixa no EGM

/egm-learn (código legado apenas) → /egm-design → /egm-review → /egm-implement → /egm-code-review, com /egm-drift-report a qualquer momento após /egm-implement (antes ou depois da revisão de código).

• Lê: o documento de design, IMPLEMENT.md, GOLDFISH.md, o histórico do git desde a base e o código.
• Escreve: apenas docs/egm/<slug>/DRIFT-REPORT.md.
• Alimenta: uma solicitação posterior de "atualizar o documento de design a partir do relatório de deriva"; /egm-design para alterações no Plano Técnico; /egm-review quando o documento atualizado precisar de revalidação.