Captura de Conhecimento
Uso automático
Antes da resposta final para qualquer tarefa do repositório, se arquivos foram alterados, testes executados ou uma decisão/descoberta/acompanhamento foi feita, crie ou atualize exatamente uma captura de sessão ativa para a sessão/fluxo de trabalho atual. Faça isso após a verificação e antes de pedir limpeza do backlog ou aprovação.
Não crie uma nova captura apenas porque o skill foi invocado novamente. Se um caminho de captura ativa for conhecido para este fluxo de trabalho, atualize esse arquivo. Caso contrário, leia .ai/raw/active-session.json como um ponteiro candidato ativo. Se não existir uma captura ativa confiável ou o fluxo de trabalho tiver mudado claramente, crie uma nova captura raw e substitua o ponteiro.
Capture detalhes suficientes da tarefa atual para uso posterior. Leia/atualize apenas a captura ativa para o fluxo de trabalho atual; não leia, atualize, deduplique, mescle, sincronize, faça commit, publique ou promova capturas não relacionadas na v0.2.
Uma captura não está completa apenas porque o auxiliar escreveu um arquivo. Não deixe Não capturado. em seções cujos fatos são conhecidos, especialmente Solicitação do usuário, Mudanças e evidências, Decisões e descobertas e Perguntas em aberto e próximos passos.
Ao atualizar uma captura ativa, escreva a captura inteira como ela deve ficar após a etapa atual do fluxo de trabalho. Não acrescente uma nota apenas de delta. Use o contexto da tarefa atual, arquivos visíveis, diffs, testes, resultados de comandos e texto de transferência como evidência; se a continuidade não estiver clara, crie uma nova captura em vez de inventar contexto faltante.
Mantenha a captura alinhada com a realidade atual, não com cada pensamento intermediário. Se uma decisão anterior mudou e o trabalho mudou junto, capture a decisão/evidência final/atual. Mantenha a decisão substituída apenas quando ela explica código implementado, um rollback, um risco não resolvido ou uma pergunta em aberto; omita opções abandonadas puramente teóricas.
Armazene capturas como .ai/raw/<pasta-do-tipo>/YYYY-MM-DDTHH-mm-ssZ--<tipo>--<slug-do-tópico>.md. Se o nome de arquivo exato existir, acrescente --2, --3 e assim por diante antes de .md.
Tipos: session -> sessions, discussion -> discussions, investigation -> investigations, decision -> decisions, handoff -> handoffs.
Para capturas do tipo session, mantenha .ai/raw/active-session.json como um ponteiro local para a captura do fluxo de trabalho ativo. Não o limpe após cada resposta final; ele suporta retomada, compactação e transferência. Substitua-o quando uma nova captura de fluxo de trabalho for iniciada.
Captura
Trate /capture como criar/atualizar captura da sessão atual. Trate /capture <tipo> como aquele tipo de captura quando <tipo> for session, discussion, investigation, decision ou handoff.
Antes da compressão de contexto, compactação ou transferência, capture primeiro se trabalho ou decisões significativas ainda não tiverem sido capturados.
Se o Node estiver disponível, o auxiliar sem dependências pode criar a primeira captura, substituir a captura ativa conhecida com --update <caminho> ou substituir a captura apontada com --update-active. Passe detalhes ricos em seções via --stdin ou escreva Markdown diretamente. O auxiliar bloqueia capturas apenas com título/resumo por padrão, pois elas perdem conhecimento útil da sessão.
node .agents/skills/knowledge-capture/scripts/capture.js --type session --title "correção do token de refresh de autenticação" --summary "Corrigido comportamento do token de refresh expirado" --stdin
node .agents/skills/knowledge-capture/scripts/capture.js --type session --title "correção do token de refresh de autenticação" --update .ai/raw/sessions/2026-07-04T18-22-10Z--session--auth-refresh-token-fix.md --stdin
node .agents/skills/knowledge-capture/scripts/capture.js --type session --title "correção do token de refresh de autenticação" --update-active --stdin
Forneça cabeçalhos Markdown de references/raw-capture-schema.md no stdin. Se a execução do Node ou shell não estiver disponível, crie ou atualize o Markdown diretamente.
Use esta ordem para capturas de sessão ativa:
- Se o caminho ativo for conhecido no contexto atual, atualize esse caminho.
- Caso contrário, leia
.ai/raw/active-session.jsoncomo um ponteiro candidato. - Se tanto o ponteiro quanto o runtime expuserem um
agent_session_ide eles coincidirem, atualize-o. - Se o ID da sessão for diferente, estiver faltando ou não estiver disponível, mas a solicitação do usuário ou transferência claramente continuar o mesmo fluxo de trabalho, atualize-o e atualize o ponteiro.
- Caso contrário, crie uma nova captura e substitua o ponteiro. Nunca escolha por adivinhação do nome de arquivo mais recente.
Salvaguardas
- Capture detalhes raw úteis, mas evite transcrições, logs grandes e arquivos inteiros.
- Coloque arquivos alterados, testes, comandos e evidências sob
Mudanças e evidências; agrupe arquivos por propósito quando vários arquivos foram alterados. - Inclua apenas comandos/resultados raros, não óbvios ou relevantes para decisões; omita comandos rotineiros que não importam depois.
- Reorganize uma captura ativa apenas para torná-la precisa e útil; não invente fatos ou mantenha silenciosamente teoria obsoleta como se ainda fosse verdade.
- Trate
agent_session_idcomo uma salvaguarda útil, não a definição de um fluxo de trabalho. Uma nova sessão de agente pode continuar o mesmo fluxo de trabalho. - Use
--agent-session-idapenas quando o runtime expuser claramente um ID estável de sessão, conversa, thread ou execução atual. Se não estiver disponível, omita-o. Nunca invente um. - Exclua segredos, credenciais, chaves de API, chaves privadas, dados privados do cliente e memória pessoal não relacionada.
- Se conteúdo sensível estiver presente, não crie a captura; resuma abstratamente primeiro.
- O estado raw/local vem do caminho
.ai/raw/e da política do skill, não de campos de captura por fluxo de trabalho. - Trate o auxiliar Node como opcional. A criação direta de arquivos ainda é válida.
Após salvar, reporte o caminho, o tipo e se foi criado ou atualizado. Se o auxiliar bloquear a captura, reporte o aviso e não salve o conteúdo raw.
Referências
- Leia
references/raw-capture-schema.mdapenas ao escrever manualmente ou alterar o esquema. - Leia
references/active-session-example.mdquando não tiver certeza de como uma captura de fluxo de trabalho atualizada deve se parecer. - Leia
references/agent-portability.mdapenas ao adaptar este skill para outro agente.