O que tirar do Obsidian, e o que deixar nele

O post anterior argumentou que um vault do Obsidian não pode ser a base de conhecimento dos seus agentes de IA: ele é privado de uma máquina, suas afirmações não têm procedência e nada marca uma nota como vencida.

Concordam com esse argumento e depois não agem, porque “mova o seu conhecimento” não é uma coisa que alguém consiga começar numa terça-feira. Este post é a metade prática. O que sai de fato, o que fica, e como o substituto se parece depois de estar rodando.

A linha, aplicada por nota

Se errar sobre esta nota levaria outra pessoa a errar junto, ela passou do ponto de um vault pessoal.

Por nota, não por vault. Essa distinção é o ponto inteiro, e é por isso que o trabalho é menor do que parece. A maior parte de um vault é pensamento — conexões pela metade, restos de reunião, coisas que você escreveu para descobrir o que pensava. Nada disso sai. O que sai é a minoria sobre a qual outras pessoas, ou um agente, agiriam.

Na prática isso tem sido menos de um quinto das notas em todos os casos que acompanhei. O resto fica exatamente onde está.

O que sai?

Convenções. “A gente faz migrations em duas etapas.” “Os handlers devolvem o erro, não fazem log dele.” Qualquer coisa formulada como a gente faz X é uma afirmação sobre o time, e uma afirmação sobre o time pertence a onde o time consegue ver e corrigir.

Decisões, com os motivos. Não só o que foi escolhido, mas o que foi descartado e por quê. Esta é a categoria de maior valor e a que mais se perde, porque o raciocínio mora na cabeça de alguém e o vault registra só a conclusão. Um agente que recebe a conclusão sem o motivo vai desfazê-la alegremente na primeira vez em que a conclusão for inconveniente.

Qualquer coisa sobre a qual um agente agiria. Se uma nota mudaria o que é escrito quando um agente a lê, ela é operacional, não pessoal. É a categoria mais nova e aquela para a qual os vaults nunca foram projetados.

Os limites. “A gente deliberadamente não faz X, e eis o porquê.” Ninguém escreve isso e todo mundo redescobre pelo caminho caro.

O que fica?

Todo o resto, e isso não é prêmio de consolação.

Ideias pela metade. Notas que têm permissão de estar erradas. A conexão que você ainda não fez. Notas de leitura, restos de reunião, aquilo que você escreveu às 2 da manhã e que fazia sentido às 2 da manhã. O Obsidian é melhor em tudo isso do que qualquer coisa pela qual você o trocaria, e é melhor porque não tem revisão, nem aprovação, nem plateia — exatamente as propriedades que o desqualificam para a outra categoria.

Um vault que guarda só isso é um vault fazendo o seu trabalho.

E as notas que são metade pensamento, metade convenção?

O caso desconfortável de sempre, e o que trava as pessoas, porque a linha parece limpa até você encontrar uma nota real de duas mil palavras remoendo um assunto com uma decisão de verdade enterrada no fim.

Divida, e é mais fácil do que parece. O pensamento fica no vault. A afirmação sai, sozinha, como uma frase. Linke de volta, se quiser.

O que você não pode fazer é mover a coisa inteira. Uma nota que é oitenta por cento tateio e vinte por cento decisão, sentada no repositório, ensina a um agente que as convenções do seu time são provisórias — e um agente que acha que uma regra é provisória vai negociar com ela na primeira vez em que a regra for inconveniente. Deixar a coisa inteira no vault tem a falha oposta: os vinte por cento de que as outras pessoas precisam ficam invisíveis, indistinguíveis da divagação ao redor.

O teste para saber se uma nota está pronta: você consegue extrair uma frase que comece com “a gente faz” ou “a gente não faz”? Se não, ainda não há nada para mover, e a nota continua fazendo o seu trabalho onde está.

Onde as notas que saem devem morar?

No repositório que elas descrevem. Não num wiki, não numa segunda ferramenta: no repo, revisadas no mesmo pull request que o código de que falam.

Essa colocação é o que faz o trabalho. Uma nota no repo é lida no momento em que alguém muda a coisa que ela descreve, porque ela está no diff. Uma nota num wiki é lida quando alguém vai procurar, que é o modo de falha que você está deixando para trás.

Isso também significa que a nota é revisada como código. Alguém aprova. Alguém responde por ela. Dois engenheiros não conseguem manter duas versões contraditórias sem que uma delas apareça num diff.

Como é uma nota depois de sair?

O formato importa menos do que quatro propriedades, e cada uma responde a um jeito pelo qual a versão do vault falhava:

• Uma afirmação por nota. “A gente faz migrations em duas etapas” é uma nota. “Notas sobre o nosso backend” é uma pasta usando o nome de uma nota, e nada lá dentro pode ser confirmado, contradito ou arquivado de forma independente.
• Ela diz de onde veio. A decisão, o incidente, o pull request. Uma afirmação que você não consegue rastrear é uma afirmação que você não consegue pesar, e mover uma afirmação irrastreável para o repositório realoca o problema em vez de resolvê-lo.
• Ela diz o que foi descartado. A conclusão sem o raciocínio é desfeita na primeira vez em que a conclusão for inconveniente — normalmente por um agente, alegremente, num diff que parece uma simplificação.
• No presente, e específica o bastante para poder estar errada. “Cuidado com migrations” não é uma nota, é um estado de espírito. Ninguém consegue agir sobre ela e ninguém jamais conseguirá provar que ela venceu.

E curta. A razão pela qual páginas de wiki não são lidas é que elas têm duas mil palavras quando a afirmação é uma linha, e uma nota que ninguém lê é uma nota que não existe — que é o mesmo desfecho de deixá-la no vault, depois de mais trabalho.

O que isto não resolve?

Mover notas para o repo resolve descoberta e revisão. Não resolve o apodrecimento, e qualquer post que dissesse o contrário estaria vendendo alguma coisa para você.

Uma nota num repositório vence exatamente na mesma velocidade que uma nota num vault. O que muda o apodrecimento não é o lugar, é um gatilho — algo que force o conhecimento a ser escrito enquanto a pessoa ainda lembra o porquê, e algo que permita tirar uma nota errada por um mecanismo, e não pela memória de alguém.

Essas são as duas propriedades a procurar no que quer que você use, e são as duas sobre as quais o CommitCycle constrói: o conhecimento é alimentado no fechamento de uma unidade de trabalho, uma linha por vez, enquanto o motivo ainda está fresco; e archived é um estado real, que é o que permite ao conjunto encolher em vez de só ficar mais confiante.

Como eu começo sem uma migração?

Não migre. Migrações de conhecimento falham pela mesma razão que migrações de qualquer coisa falham — o esforço vem na frente e o retorno fica difuso.

Em vez disso: na próxima vez que você escrever uma nota da qual outras pessoas dependeriam, escreva no repo em vez de no vault. Depois a seguinte. O vault para de crescer na categoria que dói, e o conjunto que importa começa a se acumular no lugar onde é revisado. Nada é movido e nada é perdido.

Para as notas cujos leitores são agentes e não pessoas, o destino tem um formato: uma skill é uma pasta no repositório que é carregada quando fica relevante e ignorada quando não fica, que é a coisa mais próxima de uma nota de vault que um agente consegue de fato usar.

Depois de algumas semanas, o que continuar no vault e continuar sustentando peso é uma lista curta, e a essa altura você vai saber exatamente quais notas estão nela.

Como eu sei que está funcionando?

Quatro sinais, mais ou menos na ordem em que aparecem:

1. Você para de reexplicar a mesma coisa a cada sessão nova. Este chega primeiro e é o mais imediatamente satisfatório.
2. Alguém corrige uma nota durante um code review. Isso é a colocação dando retorno: significa que a nota foi lida no momento em que a coisa que ela descreve estava sendo mudada, que é a razão inteira de ela ter ido para o repositório.
3. Um agente cita uma delas de volta para você — propondo algo e nomeando a nota de onde aquilo veio, em vez de propor algo plausível.
4. Alguém arquiva uma. Este é o sinal de verdade, e é o que demora mais. Um conjunto que só cresceu está sendo acumulado, não mantido, e vai acabar exatamente onde o vault estava: mais confiante a cada mês e menos exato.

O contrassinal é o espelho desse último. Se as notas do repositório crescem e nada nunca foi removido, você reconstruiu o vault com cerimônia extra, e o vencimento está a caminho.

Onde o CommitCycle está de verdade

Vale dizer com clareza, porque o ponto deste post é uma linha que você pode aplicar com ou sem a gente: o enforcement se instala hoje como plugin, e o pacote commitcycle do npm instala a CLI ao lado dele. O board hospedado é só por convite enquanto isto é pequeno.

Então pegue a linha e use. Não custa nada, se aplica às ferramentas que você já tem, e o argumento por baixo dela está no post anterior se você quiser conferir o raciocínio antes de confiar na conclusão.