Innate – Camada de Conhecimento Procedural Autocrescente

Função da Camada

Innate é auxiliar — nunca deve bloquear a tarefa principal. Todas as operações do Innate são de melhor esforço. Em caso de erro de ferramenta: tente novamente uma vez com uma chamada corrigida, depois abandone e continue.

Quando Recuperar

Recupere no início de uma tarefa apenas se a tarefa:

• For em um domínio com padrões recorrentes conhecidos (ex.: base de código, framework ou protocolo específicos)
• For sobre depuração ou correção de algo que pode ter sido encontrado antes
• For arquitetural/de design — decisões anteriores são importantes

Pule a recuperação para: comandos rápidos, perguntas com respostas claras, tarefas que o usuário definiu como território totalmente novo, sem contexto anterior.

Formulação da Consulta

Use a intenção canônica, não as palavras literais do usuário. Mantenha as consultas consistentes entre as sessões — a mesma classe de problema deve sempre usar a mesma forma canônica, porque o Innate acumula estatísticas de contexto por padrão de consulta.

Usuário diz	Boa consulta	Consulta ruim
"por que trava na inicialização?"	trava inicializacao sqlite init	por que trava na inicializacao
"refatore o fluxo de autenticação"	fluxo autenticacao manipulacao token sessao	refatore fluxo aut
"adicione limitação de taxa à API"	padrao middleware limitacao taxa	adicione limitacao taxa
"depure o teste instável"	teste instavel condicao corrida temporizacao	depure teste instavel

Chame: innate_recall(query=<intencao_canonica>, budget=4000, source="mcp")

Injete os fragmentos recuperados no seu contexto de trabalho. Mencione ao usuário qual (se houver) conhecimento prévio relevante foi encontrado — uma frase é suficiente.

Gancho de Recuperação Automática

Quando o Innate está instalado com ganchos, um gancho UserPromptSubmit pode injetar automaticamente um bloco <innate-recall> na conversa — ele já executou uma recuperação com filtro de relevância para o prompt e carrega um trace_id. Quando você vir esse bloco:

• Reutilize seu trace_id para o innate_record final — não chame innate_recall novamente para a mesma tarefa (isso criaria um trace duplicado e órfão).
• Trate seus fragmentos exatamente como aqueles que você mesmo recuperou: aplique o que ajuda e feche com um veredito por fragmento (veja abaixo).
• Se o bloco estiver ausente e a tarefa justificar, recupere manualmente como acima.

O gancho é filtrado por relevância, então seu silêncio significa "nada pontuou o suficiente" — não "não existe conhecimento". Recupere manualmente se suspeitar de conhecimento prévio relevante que o filtro perdeu.

Quando Registrar

Registre após uma tarefa que produziu um resultado real (sucesso ou falha). Pule o registro para:

• Ida e volta exploratória sem resultado definitivo
• Tarefas em que o usuário interrompeu antes da conclusão
• Recuperação pura (o usuário só fez uma pergunta, nada foi construído ou alterado)

Regras de Resultado

Situação	resultado
Tarefa concluída, usuário confirmou ou aceitou o resultado	ok
Tarefa falhou, abordagem estava errada, usuário teve que corrigir o rumo	fail
Sessão interrompida, resultado incerto	unknown

Veredito por Fragmento — Obrigatório

Este é o contrato mais importante do Innate: a classificação de confiança só é tão boa quanto a precisão do que você relata aqui. Toda recuperação que trouxe fragmentos (manual ou por gancho) dever ser fechada com um veredito por fragmento. Para cada fragmento que foi colocado diante de você, ele se enquadra exatamente em um de três grupos:

Veredito	O que significa	Onde vai
Usado + Ajudou	Você o aplicou e ele economizou tempo / evitou um erro	used=[id] e feedback_up=[id]
Usado + Enganou	Você o aplicou, mas ele estava errado ou te levou pelo caminho errado	used=[id] e feedback_down=[id]
Não usado	Recuperado, mas você nunca o aplicou	omita completamente (não liste em used)

Regras que mantêm o sinal limpo:

• used lista apenas fragmentos que você referenciou ativamente em seu raciocínio ou saída — normalmente um a três. Nunca o preencha com fragmentos meramente recuperados.
• Se você não aplicou nada, isso é um sinal real e valioso: defina used=[] explicitamente (conhecido-zero). Não pule o registro — silêncio não é o mesmo que "nada ajudou".
• Um fragmento que você usou quase sempre deve carregar também um sinal positivo ou negativo. Um fragmento usado sem veredito desperdiça a entrada de classificação mais forte que você pode dar.
• Seja honesto sobre feedback_down. Um fragmento errado que você marca para baixo é revisado e arquivado; um fragmento errado que você deixa sem marca continua enganando sessões futuras.

Resumo da Saída — Formato Estruturado

Escreva uma frase autocontida que um agente futuro possa usar diretamente. Use esta estrutura:

<o que foi feito ou aprendido> — <restrição ou método-chave> — <quando isso se aplica>

Exemplos bons:

• Corrigiu a detecção do modo WAL do SQLite verificando a resposta de PRAGMA journal_mode em vez de assumir WAL — dispara em qualquer nova conexão de BD em configurações multiprocesso
• Resolveu teste de autenticação instável injetando um clock simulado — o tempo real do sistema causa condição de corrida na verificação de expiração do token
• A limitação de taxa deve ser aplicada antes do middleware de autenticação, não depois — caso contrário, requisições não autenticadas ignoram o limitador

Exemplos ruins (vagos demais para reutilizar):

• Corrigiu o bug
• Ajudei o usuário com autenticação
• O problema era temporização

O output_summary se torna o fragmento de conhecimento reutilizável. Se parecer uma história, reescreva-o como um princípio. Prefira a forma geral e transferível — remova nomes de repo/arquivo/função e identificadores únicos, e formule a lição para que ajude no próximo projeto também; mantenha detalhes específicos do projeto apenas quando a lição não puder ser generalizada sem perder seu significado. Se você não puder escrever um resumo útil, defina output="unknown" e pule o registro.

Chame: innate_record(trace_id=<id>, outcome=<ok|fail|unknown>, used=[<chunk_ids>], output_summary=<frase>)

Feedback Explícito — Por Que é Importante

As listas feedback_up / feedback_down da tabela de veredito acima são o sinal mais rápido para qualidade do conhecimento e impulsionam diretamente a classificação e o ciclo de vida: dois sinais negativos no mesmo fragmento disparam uma revisão de governança; cinco disparam o arquivamento automático. Por outro lado, usado + feedback_up repetido é o que promove um fragmento pending para active. Reter feedback congela a base de conhecimento; fornecê-lo é como o bom conhecimento sobe e o ruim cai.

Nomeação — Rara, Explícita

Use o campo nomination apenas para lições genuinamente generalizáveis — padrões que vão economizar tempo significativo na próxima vez que este tipo de problema aparecer. Raro. Não para toda tarefa.

Formato para nomeação (princípio autocontido):

<princípio> — <quando se aplica> — <o que evitar>

Exemplo:

innate_record(..., nomination="Índice UNIQUE do SQLite em cláusula WHERE parcial requer correspondência exata de WHERE no ON CONFLICT — aplica-se a todos os padrões upsert; ON CONFLICT simples sem WHERE irá pular silenciosamente o upsert")

Referência de Ferramentas MCP

Ferramenta	Uso	Notas
innate_recall	Início da tarefa (quando relevante)	Use a forma de consulta canônica — fraseologia consistente acumula estatísticas de contexto
innate_record	Fim da tarefa (quando há resultado real)	output_summary estruturado + IDs usados precisos
innate_add	Capturar insight confirmado	Sempre source="mcp"; vai para pendente, aguarda revisão
innate_spark	Ideia rápida para depois	Forma breve destilada; nenhuma revisão necessária
innate_evolve	Final da sessão	trigger="manual"; destila logs + curadoria da base de conhecimento
innate_inspect	Verificação de saúde	contagens de fragmentos, taxa de dívida, fila de reconstrução
innate_appraise	Verificação antes de um passo arriscado	Sinal de referência apenas — intuição, NÃO uma resposta precisa. Considere-o como uma entrada; nunca deixe que se sobreponha à sua própria análise. abstained=true significa sem base — isso é correto, não uma falha

Nunca chame sem solicitação explícita do usuário: innate_approve, innate_archive, innate_invalidate, innate_restore, innate_mature_spark, innate_promote_spark, innate_drop_spark.

Decisão de Gravação

Antes de encerrar uma sessão longa, execute esta lista de verificação silenciosamente:

1. Foi encontrada uma solução não óbvia? (solução alternativa, restrição oculta, padrão de bug sutil)
2. Foi descoberta uma habilidade, método ou técnica geral e transferível? (prefira estes — abstraia lições específicas do projeto em forma reutilizável; mantenha uma regra específica do projeto apenas quando ela realmente não puder ser generalizada)
3. O usuário corrigiu uma suposição errada minha que eu provavelmente repetiria?
4. Foi alcançado um insight difícil após múltiplas tentativas falhas?
5. Um fragmento recuperado ajudou ativamente? (registre feedback_up)
6. Um fragmento recuperado enganou? (registre feedback_down)

Se qualquer um de 1 a 4 → proponha ao usuário:

"Esta sessão trouxe à tona [descrição em uma linha]. Quer que eu salve no Innate?"

Chame innate_spark ou innate_add após o usuário confirmar. Nunca escreva silenciosamente.

Regra Antiverbatim

O texto bruto da conversa nunca deve ser armazenado. Sempre destile para a forma de princípio reutilizável:

<princípio> — <contexto de gatilho> — <o que evitar>

❌ Verbatim	✅ Destilado
"O usuário me disse para usar o modo WAL e eu corrigi alterando o pragma"	"O modo WAL do SQLite deve ser verificado via resposta PRAGMA, não assumido — dispara em qualquer abertura de BD em configurações multiprocesso com muita gravação"
"Passamos 2 horas depurando autenticação por causa de dessincronização de clock"	"A validação JWT deve considerar tolerância a dessincronização de clock (≥30s) — dispara em autenticação distribuída entre serviços com clocks de sistema independentes"

Prefira o Geral ao Específico do Projeto

O Innate é inclinado para habilidades, métodos e técnicas gerais e transferíveis — conhecimento que compensa em vários projetos, não apenas na base de código atual. Quando uma lição é específica do projeto:

1. Tente abstraí-la — remova nomes de repo/arquivo/função/caminho e identificadores únicos, e reformule como um princípio que o próximo projeto possa reutilizar.
2. Salve a forma abstraída. Mantenha detalhes concretos específicos do projeto apenas quando a lição genuinamente não puder ser generalizada sem perder seu significado.

❌ Limitado ao Projeto	✅ Generalizado
"Neste repo, record() deve ser executado dentro de BEGIN IMMEDIATE"	"Mutações de estado em várias etapas que precisam ser atômicas pertencem a uma transação exclusiva, não a commits por etapa — aplica-se a qualquer escritor SQLite com processos concorrentes"
"Defina recall.budget=4000 na tabela meta"	"Exponha o orçamento de recuperação como um parâmetro ajustável em vez de codificá-lo — permite que o recall escale com a janela de contexto sem alterações de código"

Sparks vs. Notas

Use innate_spark	Use innate_add
Ideia rápida, palpite incompleto	Princípio reutilizável confirmado
Ainda não validado	Validado nesta sessão
Usuário diz "anote isso para depois"	Usuário diz "lembre-se desta regra"

Fallback via CLI (se MCP não configurado)

# Recuperação
innate recall "<intencao_canonica>" --top 5 --format json --source cli

# Registro com resumo estruturado
innate record <trace_id> --outcome ok \
  --used <id1>,<id2> \
  --output-summary "Corrigiu X fazendo Y — aplica-se quando Z" \
  --feedback up  # ou down

# Capturar insight
innate add "<princípio> — <gatilho> — <o que evitar>" \
  --trigger "<contexto de 2-5 palavras>" \
  --source agent

# Spark rápido
innate spark "<ideia destilada em 1-2 frases>"

# Final da sessão
innate evolve --trigger manual
innate inspect

Comandos

Os comandos de barra abaixo são instalados automaticamente em ~/.claude/commands/ por innate install e atualizados em cada nova execução de innate install. Cada bloco command define um comando: metadados antes de ---, corpo (o prompt do agente) após ---.

name: innate-recall
description: Recuperar conhecimento prévio do Innate para o contexto da tarefa atual
---
Execute innate_recall para o contexto da tarefa atual e injete o resultado nesta conversa.

Se o usuário forneceu uma consulta após o comando, use exatamente essa consulta para a recuperação.
Se nenhuma consulta foi fornecida ($ARGUMENTS está vazio), deduza a consulta da mensagem mais recente
do usuário ou da intenção da tarefa atual — use a **intenção canônica** (ex.: `sqlite wal mode init`,
não `por que trava`). Mantenha a forma da consulta consistente com como você formularia a mesma
classe de problema no futuro.

Passos:
1. Formule a string de consulta canônica (de $ARGUMENTS ou intenção deduzida).
2. Chame `innate_recall` com `query=<consulta>`, `budget=4000`, `source="mcp"`.
3. Se conhecimento for retornado: resuma em uma frase o que foi encontrado e injete os
   fragmentos relevantes no contexto.
4. Se vazio: diga "Nenhum conhecimento prévio encontrado para: <consulta>" — não invente.
5. Salve o `trace_id` para uso posterior em `/innate-record`.

name: innate-record
description: Fechar o trace atual do Innate com um resultado e resumo estruturado
---
Feche o trace atual do Innate com um resultado e resumo.

Analise $ARGUMENTS em busca de:
- outcome: um de `ok`, `fail`, `unknown` (padrão: `ok` se não especificado)
- Qualquer texto restante se torna o output_summary substituído

Passos:
1. Identifique o trace_id ativo da chamada mais recente de `innate_recall` nesta sessão.
   Se nenhum trace_id estiver disponível, diga "Nenhum trace ativo — execute /innate-recall primeiro."
2. Determine quais IDs de fragmentos recuperados foram **realmente usados** na resposta final (não
   apenas candidatos recuperados). Seja preciso — fragmentos recuperados não usados NÃO devem ser listados.
3. Escreva um output_summary estruturado para um agente futuro lendo diretamente:
   Formato: `<o que foi feito> — <restrição/método-chave> — <quando isso se aplica>`
   Se o usuário forneceu texto de resumo em $ARGUMENTS, use esse.
4. Avalie o feedback:
   - Se algum fragmento foi diretamente útil → inclua `feedback_up=[chunk_id]`
   - Se algum fragmento estava errado/enganoso → inclua `feedback_down=[chunk_id]`
5. Chame `innate_record` com `trace_id`, `outcome`, `used=[<chunk_ids>]`,
   `output_summary` e feedback se aplicável.
6. Confirme: "Trace <trace_id> registrado como <outcome>."

name: innate-save
description: Salvar um insight confirmado no Innate como um fragmento de conhecimento pendente
---
Salve um insight confirmado no Innate como um fragmento de conhecimento pendente.

$ARGUMENTS é o texto do insight a ser salvo (obrigatório). Se vazio, pergunte: "Qual insight você
gostaria de salvar?"

Passos:
1. Analise $ARGUMENTS como o conteúdo do insight.
2. Di
tinue...