LucioLiu/track-record

track-record: Disciplina de Ciclo de Calibragem de Julgamentos

Registre um julgamento, liquide-o quando a realidade der o resultado, e destile os desvios recorrentes em regras. O sinal de aprendizado é resultado real vs. seu julgamento original (fechamento de ciclo cruzando o tempo), não "correção do usuário" — esta última é território de outra classe de ferramentas. Este documento é sobre a disciplina da calibragem (ensinar ao agente que faz julgamentos como registrar, liquidar e transformar desvios em regras), não um sistema de previsão (não inclui liquidadores automáticos nem back-end estatístico). Para detalhes, leia references/ conforme necessário: formato do livro-razão ledger-format.md, liquidação settlement.md, destilação distill.md, tabela de desculpas rationalizations.md.

Motivação em uma frase: Registrar sem retroalimentar = usar intuição não verificada para sempre.

Origem Verdadeira e Camada de Instalação

A origem verdadeira única desta skill é o repositório GitHub (endereço na seção "Versão e Auto-Verificação" no final). Os diretórios de descoberta nativos das plataformas são apenas imagens de instalação reconstruíveis: Claude Code usa ~/.claude/skills/; outros hosts instalam em seus respectivos diretórios de descoberta de skills (o caminho varia conforme o harness; antes de instalar, consulte a documentação do host ou teste). Implantações internas de equipe podem criar um diretório de origem verdadeira interno com espelhamento síncrono, mas não mantêm um conjunto de documentos separado em vários lugares. Para desinstalar, basta excluir o diretório; esta skill não deixa nenhum estado fora do arquivo de livro-razão.

Mecanismo de Cinco Anéis

Anel Um · Log: Registre ao Fazer um Julgamento

Sempre que fizer um julgamento verificável — previsão, afirmativa de seleção, avaliação de risco, "esta mudança será melhor" — registre uma entrada no livro-razão (se o arquivo de livro-razão não existir, crie-o usando o modelo em references/ledger-format.md antes do primeiro registro). Sete campos:

# | Data | Julgamento/Previsão | Base | Gatilho de Retroalimentação | Confiança e Probabilidade | Resultado Real | Destilação do Desvio

Cinco requisitos rígidos:

1. Use a frase "Aposto que..." na base, explicitando o ponto falsificável: "Aposto que os dados quentes estão concentrados e a taxa de acerto do cache ultrapassa 80%" é liquidável; "O desempenho deve ser bom" não é.
2. Escreva o gatilho de retroalimentação como um evento observável: "Após duas semanas em produção, veja o relatório P95 semanal" ou "Se o erro X reaparecer, considere falha" — este é o contrato entre registro e liquidação. Escreva o critério de sucesso como faria uma rubrica de avaliação: verificável, indique a forma da evidência, escreva o alvo de observação, não os passos de operação (especificar ferramentas específicas pode falhar silenciosamente se elas não existirem), e preveja atalhos excluindo-os explicitamente. Um julgamento para o qual não é possível escrever um gatilho observável provavelmente deve ser excluído no Anel Dois.
3. Anexe uma probabilidade numérica ou intervalo; proíba adjetivos nus: "Muito provável" é um véu; "75%" pode ser refutado. No início, com poucas amostras, pode-se usar o nível de probabilidade de feedback rápido (valor na Tabela de Única Fonte de Limiares do Anel Cinco) para acumular rapidamente dados de calibragem.
4. Marque o nível de confiança HIGH / MED / LOW: O nível de confiança vincula diferentes ações após a retroalimentação (encaminhamento no Anel Cinco).
5. O campo de destilação pode ser pré-preenchido com riscos bilaterais: Escreva tanto o risco positivo quanto o negativo para evitar virar apenas para um lado.

Adicional: Antes de registrar, verifique entradas semelhantes no livro-razão (perspectiva externa) — a taxa de acerto histórica de julgamentos semelhantes é uma âncora básica; primeiro pegue a âncora, depois faça ajustes para este caso.

Anel Dois · Triage: Registre Apenas na Zona de Dificuldade Moderada

Registre apenas julgamentos na zona Goldilocks:

• Muito Fácil (quase certo de estar correto): Não registre. A liquidação não produz informação.
• Incognoscível (não é possível escrever um gatilho de retroalimentação observável): Não registre. Se registrar, ficará apodrecendo na área pendente.
• Moderado (tem incerteza real, e a realidade dará uma resposta): Registre.

Vários julgamentos em uma tarefa → use Grupo de Julgamentos: Um registro pai + julgamentos filhos, cada um com seu próprio número e liquidação independente, para evitar "tudo ou nada" e também reduzir o número total de entradas.

O Triage trata da sobrecarga de registro — quando o livro-razão está cheio de entradas não liquidáveis, a disciplina morre devido ao custo irrecuperável. Nota: "Muito pequeno para registrar" não é um critério de Triage (veja a tabela de refutação de desculpas). A própria exclusão pelo Triage é uma previsão: Um julgamento oralmente considerado "muito fácil" que é posteriormente refutado pela realidade = constitui automaticamente uma entrada de Autocorreção a ser registrada — a saída de exclusão não é uma porta dos fundos para evitar o registro.

Anel Três · Settle: Liquidação é um Mecanismo Rígido, Não uma Virtude

Quatro Gatilhos Rígidos, qualquer um acionado liquida a entrada correspondente:

1. O objeto do julgamento já está em produção há várias semanas;
2. O usuário dá feedback sobre o resultado (bom / ruim / erro);
3. O julgamento é exposto a uma falha em situação real;
4. Durante uma revisão geral.

Disciplina Rígida de Abertura: O livro-razão é colocado no topo visível; toda vez que abrir, dê uma olhada na área de entradas ativas — se houver entradas vencidas, resolva-as antes de trabalhar.

Tratamento Obrigatório por Tempo Limite (sem precedentes externos para este mecanismo, é um design original desta skill): Entradas cuja janela esperada de gatilho de retroalimentação já passou sem liquidação, tenha que escolher uma de três opções, sem uma quarta opção "esperar mais":

1. Liquidar Imediatamente: Liquide com a evidência disponível; se a evidência for insuficiente, escreva "evidência insuficiente" honestamente no campo de resultado;
2. Marcar como [Não Liquidável] e anotar o motivo (objeto já desapareceu / evento gatilho não pode mais ocorrer / padrão não pode ser comparado com a realidade);
3. Prorrogação Explícita: Limite superior na Tabela de Única Fonte de Limiares do Anel Cinco, e deve escrever um novo evento gatilho observável; não é permitida prorrogação nua.

Liquidante Independente: A liquidação é executada por um contexto não-participante (nova sessão / agente independente), que só compara as entradas do livro-razão com a evidência real contra o gatilho de retroalimentação, e não ouve explicações do contexto participante — elimina autoavaliação. Quando o padrão não pode ser comparado com a realidade, marque como [Não Liquidável], não force a liquidação.

Evidência de liquidação = observação da realidade (logs / artefatos / feedback existente do usuário). Não faça ping no usuário para apressar o resultado — liquidação é ler a realidade, não criá-la.

Pode conectar hooks da plataforma anfitriã para transformar a verificação de abertura/fechamento em lembretes mecânicos (método opcional; esta skill não inclui nenhum hook ou script), veja configuração de exemplo em references/settlement.md.

Anel Quatro · Backfill: Como Escrever a Retroalimentação

• Suporta Incremental: Julgamentos filhos que podem ser liquidados são liquidados primeiro, o estado da entrada é marcado como [Parcial·data]. Estados: [Pendente] [Parcial·data] [Liquidado] [Não Liquidável] [Autocorreção].
• Liquidar Grupo Separadamente: Julgamentos filhos registram seus próprios acertos/erros, sem responsabilidade coletiva do grupo.
• Registrar Mesmo se Refutado: A retroalimentação pode refutar o próprio julgamento original — entradas refutadas são as mais valiosas de todo o livro-razão; registre o resultado e a lição.
• Entradas [Autocorreção]: Erros flagrados na hora pelo usuário também são registrados, marcados como [Autocorreção] — errar é material, não omita por vergonha.
• Alerta n=1: Conclusões tiradas de um único caso escrevem um alerta de tamanho amostral no campo de resultado; proibido alterar regras diretamente com base em um único caso (encaminhamento no Anel Cinco).
• Interpretável e Acionável: Apenas escrever "errou" não é retroalimentação — escreva em qual elo errou, se a direção foi superestimação ou subestimação. Feedback não é igual a feedback eficaz.
• Equilíbrio Sub-reação / Sobre-reação: Um único erro de retroalimentação não derruba toda uma regra existente; faça atualizações frequentes e pequenas, sem grandes viradas.

Anel Cinco · Distill: Desvio → Regra → Mecanismo

Três níveis de escada:

1. Caso Isolado = Registro Individual: Permanece no livro-razão, não mexe nos arquivos de regras.
2. Reincidência de Desvio do Mesmo Tipo Atinge a Linha de Subida para Regra (veja tabela abaixo) = Sobe para Regra: Escreva uma regra em linguagem forte (nomeie o cenário + anexe exemplo) e coloque-a no arquivo de regras correspondente. A determinação de "mesmo tipo" usa Impressão Digital do Desvio: direção do desvio + tipo de objeto + mecanismo de falha, todos consistentes contam como mesmo tipo; a contagem acumula entre entradas.
3. Regra Implementada Ainda Violada Atinge a Linha de Subida para Mecanismo (veja tabela abaixo) = Sobe para Mecanismo: O que o texto não consegue controlar é entregue a processos / hooks / modelos obrigatórios — substitui a consciência pela execução determinística.

Encaminhamento por Confiança: HIGH (evidência de retroalimentação sólida) → pode alterar regras diretamente; MED (padrão emergente) → registra em área de observação aguardando próximo caso; LOW (caso isolado / evidência fraca) → apenas registra, proibido mexer em regras.

Fecho do Ciclo de Retroalimentação: Cada subida deve escrever "Retroalimentado para §<seção>" — uma destilação que não chega ao arquivo de regras não está completa, é apenas opinião. Após a subida, a entrada original é movida para a área de arquivamento, para evitar que o mesmo desvio seja contado repetidamente.

Disciplina de Arquivamento: Entradas liquidadas são movidas para a área de arquivamento; a área ativa contém apenas entradas pendentes e parciais; quando um arquivo atinge a linha de compressão (veja tabela abaixo), ele é comprimido e consolidado; o arquivamento não exclui.

Tabela de Única Fonte de Limiares (único local de definição em todo o conjunto de arquivos; todas as outras referências devem citar esta tabela, não escrever números em outro lugar)

Nome do Limiar	Valor	Ponto de Ação
Linha de Subida para Regra	Reincidência de desvio do mesmo tipo acumulada ≥ 2 vezes	Destilação Nível 2: Caso Individual → Regra
Linha de Subida para Mecanismo	Regra implementada violada novamente ≥ 1 vez	Destilação Nível 3: Regra → Mecanismo
Limite de Prorrogação	Cada julgamento tem limite de 1 prorrogação	Opção de tempo limite de liquidação
Linha de Compressão por Inchaço	Arquivo único com mais de 80 linhas	Livro-razão principal e arquivo de meta-calibragem
Linha de Mensagem Muito Curta	Menos de 10 caracteres	Filtro de falso positivo
Nível de Probabilidade de Feedback Rápido	50%	Nível de probabilidade uniforme para registros iniciais
Linha de Amostra de Feedback Rápido	Cerca de 20 entradas	Tamanho mínimo de amostra necessário para expor desvio sistemático em julgamentos de 50% (para 90%, é necessário amostra grande para expor desvio)

Camada de Proteção contra Erros

Tabela de Refutação de Desculpas (Trecho Central; tabela completa e Red Flags em references/rationalizations.md)

Desculpa	Refutação
"Este caso tinha circunstâncias especiais, não conta"	As circunstâncias são sempre especiais. Escreva a especificidade no campo de destilação do desvio, não como motivo para cancelar a liquidação.
"O resultado ainda não se concretizou totalmente, não vou liquidar ainda"	Das três opções de tempo limite, não há "esperar mais". Se quiser esperar, prorrogue explicitamente e escreva um novo evento gatilho.
"Este julgamento é muito pequeno, não vale a pena registrar"	Se vale a pena fazer, vale a pena registrar; se realmente não vale, deveria ter sido excluído no Triage, não registrado e depois não reconhecido.
"Ninguém lê a retroalimentação"	Quem lê é você, quando fizer o próximo julgamento. O livro-razão fornece dados para julgamentos futuros, não é uma performance para o público.
"Eu me lembro, estava mais ou menos certo"	Lembrar ≠ verificar. Liquidar com base na memória é como usar intuição não verificada para avaliar intuição não verificada.

Princípio meta: Violar a letra é violar o espírito — encontrar uma brecha literal no texto para contorná-lo não é inteligência, é a definição de falha desta disciplina.

Filtro de Falso Positivo (Ao tratar mensagens do usuário como evidência de liquidação ou sinal de autocorreção)

• Apenas correções de mensagens reais do usuário são consideradas sinais: saídas de ferramentas, recontagens, mensagens entre agentes não contam como "correção".
• Ignore mensagens muito curtas (comprimento na Linha de Mensagem Muito Curta na Tabela de Única Fonte de Limiares do Anel Cinco): um "ok" não sustenta uma liquidação.
• Sinais reconhecidos devem imediatamente seguir a saída correspondente para contar — um "bom" três rodadas depois pode estar elogiando outra coisa; proibido correspondência ampla nua como "sim".

Meta-Calibragem: O Livro-Razão Também Precisa Ser Calibrado

O track-record é também uma cadeia de regras propensa a desvios. Configure um arquivo de meta-calibragem (por exemplo, meta.md) para registrar: qual tipo de conclusão de retroalimentação foi adotada, qual foi rejeitada, qual foi reescrita. Antes de executar esta disciplina, dê uma olhada: tipos de destilação consistentemente rejeitados perdem peso; os consistentemente adotados ganham peso.

O livro-razão principal e o arquivo de meta-calibragem estão ambos sujeitos à linha de compressão por inchaço (veja Tabela de Única Fonte de Limiares no Anel Cinco) — quando a ferramenta de calibragem incha fora de controle, é a replicação do próprio modo de falha que ela visa prevenir.

Base de Design (Lição Dogfood, Anônima)

O design de liquidação rígida desta skill veio de uma prova de conceito anônima: um protótipo de livro-razão interno operou por cerca de 3 semanas, registrou 30+ entradas, e a grande maioria permaneceu sempre como [Pendente]; a área de arquivamento estava vazia — "apenas entrada, sem saída" é o modo de falha número um empiricamente comprovado. As poucas retroalimentações concluídas foram quase todas acionadas por eventos externos (flagrado na hora / questionamento de aceitação / auditoria independente), e quase nenhuma foi acionada por varredura espontânea do registrador.

Conclusão: Disciplina suave quebrará. O mecanismo de liquidação rígida (tratamento obrigatório por tempo limite + varredura rígida na abertura + hooks opcionais) não é opcional; é a razão de ser desta skill.

Versão e Auto-Verificação

• Versão atual: 1.0.0 (consistente com plugin.json).
• Repositório: https://github.com/LucioLiu/track-record
• Auto-verificação: Se instalado via plugin, o mecanismo de atualização do host acompanhará o número de versão; se clonado manualmente / copiado como arquivo único, faça um diff deste arquivo com o branch main do repositório para saber se está desatualizado.