gzb1128/skill-forge

Habilidade acionada manualmente. disable-model-invocation: true impede que o modelo invoque este workflow automaticamente durante a tarefa. Quando instalado a partir deste plugin, invoque-o deliberadamente como /agent-docs:learn ao final de uma sessão. Não adicione hooks, tarefas em segundo plano, comportamento de disparo automático, armazenamento em tempo de execução, bancos de dados vetoriais, integração MCP ou sistemas de memória externos.

Revise o que aconteceu nesta sessão e produza propostas de memória verificadas e revisáveis para o arquivo AGENTS.md apropriado. Não edite arquivos até que o usuário veja o diff proposto e o aprove explicitamente.

Princípio de Não-Derivabilidade

Registre APENAS informações que NÃO PODEM ser derivadas do código-fonte. Antes de propor qualquer entrada de Hidden Knowledge, pergunte:

O próximo agente ou humano pode descobrir isso lendo o código, executando git log ou verificando a documentação existente?

Se sim, NÃO registre como hidden knowledge. O padrão é alto. A maior parte do conhecimento pertence ao código-fonte, mensagens de commit ou documentação existente, não no AGENTS.md.

Passo 1: Extrair insights candidatos

Revise o histórico da sessão atual e liste insights candidatos. Candidatos geralmente vêm de dependências ocultas, falhas enganosas, workarounds específicos do projeto, ordenação crítica, descoberta de comandos ou lacunas na documentação.

Não escreva nada ainda. Primeiro classifique cada candidato.

Passo 2: Classificar candidatos

Classificação	Destino	Regra
Hidden Knowledge	AGENTS.md relevante mais próximo, sob ## Hidden Knowledge	Apenas para dependências ocultas não deriváveis, erros enganosos, workarounds, peculiaridades ou ordenação crítica
Quick Reference	Tabela de Quick Reference do AGENTS.md raiz	Comandos comuns de build, test, lint, run, codegen, clean ou outros
Rule	Reportar apenas o destino sugerido	Convenção da equipe ou limite rígido; não crie ou modifique docs/rules/ a partir de /agent-docs:learn
Doc	Reportar apenas o destino sugerido	Nota de design mais longa, troubleshoot, runbook ou biblioteca; não crie ou modifique docs a partir de /agent-docs:learn
Skip	Nenhuma escrita	Derivável, único, duplicado, desatualizado, genérico ou não verificável

Candidatos a Hidden Knowledge

Apenas candidatos que passam no teste de não-derivabilidade podem se tornar hidden knowledge:

1. Dependências ocultas: Arquivos ou módulos que devem ser alterados juntos, mas não estão obviamente conectados.
2. Erros enganosos: Mensagens de erro que apontam para o local ou causa errados.
3. Workarounds e peculiaridades: Comportamento específico do projeto que difere do padrão.
4. Ordenação crítica: Operações que devem ocorrer em uma sequência específica.

Critérios de Skip

Pule candidatos que são:

• Padrões de código, arquitetura ou estrutura de arquivos visíveis pela leitura do código-fonte.
• Histórico Git ou alterações recentes que git log ou git blame já registram.
• Soluções de depuração onde a correção está agora no código e a mensagem do commit deve carregar o contexto.
• Já presentes em AGENTS.md, docs/rules/ ou README.
• Comportamento padrão de linguagem ou framework.
• Comandos não óbvios que pertencem ao Quick Reference, não ao Hidden Knowledge.
• Detalhes efêmeros da sessão, incluindo tentativas que falharam temporariamente.
• Alegações não verificadas.

Passo 3: Verificar cada candidato retido

Cada candidato retido precisa de evidência explícita antes de ser proposto:

Menções do candidato	Evidência de verificação
Caminho de arquivo	Confirme que o caminho existe com ls ou lendo o arquivo
Função, tipo, comando ou símbolo	Confirme que existe com pesquisa ou uma busca com reconhecimento de linguagem
Comportamento ou restrição	Execute o menor comando relevante, inspecione a origem ou explique por que a execução direta é insegura
Conteúdo existente do AGENTS.md	Leia a seção alvo e verifique se há entradas desatualizadas ou duplicadas

Se a verificação falhar, classifique o candidato como Skip e explique a verificação falhada. Se a verificação não puder ser realizada com segurança, relate como não verificado e não proponha uma escrita.

Passo 4: Escolher o alvo

Escolha o AGENTS.md mais próximo do escopo afetado:

Escopo do insight	Arquivo alvo
Afeta o projeto inteiro	AGENTS.md raiz
Afeta um pacote específico	<pacote>/AGENTS.md
Afeta um módulo complexo	<pacote>/<módulo>/AGENTS.md, apenas se os critérios de subpacote forem atendidos

Para Hidden Knowledge, anexe ou crie uma seção ## Hidden Knowledge perto do final do AGENTS.md alvo. Mantenha cada insight em 1-3 linhas.

Para Quick Reference, proponha uma atualização de linha na tabela do AGENTS.md raiz.

Para Rule e Doc, relate apenas o destino sugerido. Não crie ou modifique regras, documentos de design, troubleshoot, runbooks ou documentos de biblioteca a partir deste comando.

Passo 5: Mostrar alterações propostas primeiro

Antes de editar qualquer arquivo, mostre todas as propostas neste formato:

## Propostas de Aprendizado

### 1. `<classificação>` -> `<arquivo alvo>`

**Por que:** <motivo em uma linha pelo qual isso ajuda sessões futuras>

**Verificação:** <evidência de caminho/símbolo/comando/comportamento>

**Ação:** <adicionar/atualizar/pular/apenas relatar>

```diff
- <linha existente, apenas ao atualizar uma entrada existente aprovada>
+ <adição ou substituição exata proposta>
```

### Candidatos Pulados

1. `<candidato>` -> pulado porque <motivo>

### Sugestões Apenas para Relatório

1. `<candidato>` -> pertence a <destino sugerido>, não tratado por `/agent-docs:learn`

Não pule a etapa de diff e aprovação. Mesmo que o usuário peça para aplicar rapidamente, o usuário deve ver as alterações exatas propostas e aprová-las primeiro.

Passo 6: Aplicar apenas alterações aprovadas

Após a aprovação:

1. Aplique apenas as propostas que o usuário aprovou.
2. Preserve a estrutura existente do AGENTS.md e mantenha as adições concisas.
3. Não realize limpeza geral a partir de /agent-docs:learn; use /agent-docs:remember para memória existente desatualizada, duplicada ou mal colocada.
4. Relate o que mudou, onde mudou e quais candidatos foram pulados.

Procedimento

1. Revise o histórico da conversa em busca de insights candidatos.
2. Classifique cada candidato como Hidden Knowledge, Quick Reference, Rule, Doc ou Skip.
3. Aplique o teste de não-derivabilidade a candidatos Hidden Knowledge.
4. Verifique cada candidato retido e registre evidências.
5. Escolha o alvo AGENTS.md correto ou destino apenas para relatório.
6. Mostre diffs propostos e candidatos pulados.
7. Aguarde aprovação explícita do usuário.
8. Aplique apenas as alterações aprovadas no AGENTS.md.
9. Relate escritas finais, pulos e sugestões apenas para relatório restantes.