consolidação-de-alegações-de-conhecimento

Revisão de consolidação de alegações

Leia as convenções compartilhadas e a publicação antes de escrever.

Alegações se acumulam mais rápido do que as páginas são curadas. knowledge_remember salva uma alegação sem uma página de assunto quando nenhum nome nela corresponde exatamente a uma página, e a manutenção agendada knowledge_relink vincula apenas alegações cuja página de origem é uma página de entidade ou cujo texto nomeia exatamente uma página. Alegações vinculadas também se acumulam: uma página hub coleta instantâneos de estado, duplicatas e alegações que pertencem a um assunto mais específico. Esta revisão executa um procedimento sobre um escopo escolhido. Trabalhe nesta ordem: escolha o escopo, vincule, depois duplicatas, alegações substituídas e séries de instantâneos, depois prosa da página.

1. Escolha o escopo e enumere-o

Chame knowledge_status para o escopo pretendido e knowledge_ontology para a impressão digital atual. Em seguida, enumere exatamente um conjunto inicial:

• Resíduo não vinculado (o padrão, e o único escopo das execuções do escriba). Execute knowledge_relink sem dryRun primeiro para que cada alegação lembrada que ele pode vincular seja vinculada. Em seguida, liste o resíduo com knowledge_relink dryRun: true, include: "all" e limit: 10, seguindo nextCursor: toda alegação atual sem página vinculada e sem página de origem, independentemente de qual ferramenta a salvou. Cada chamada relata no máximo 10 exemplos por resultado, então um limite de 10 retorna todas as alegações que examinou.
• Uma página, para uma página hub ou uma página acima de seu orçamento de tamanho. Liste suas alegações atuais com knowledge_connections id, direction: "claims", view: "full" e includeCards: true, seguindo nextOffset com os mesmos filtros. Reinicie quando snapshot mudar. Em um hub, agrupe primeiro a partir dos cartões e trabalhe um grupo de cada vez; não leia todas as alegações na íntegra de antemão.
• Um assunto, opcionalmente desde uma data. Quando o assunto tem uma página, liste suas alegações com knowledge_timeline entity, timeField: "recorded_at" e since, seguindo nextOffset. Também procure alegações arquivadas em outro lugar ou não vinculadas com knowledge_grep kind: "claim", os nomes distintos do assunto (um número de PR, um SHA de commit, um nome de funcionalidade) e o mesmo since/timeField. Mantenha apenas alegações que são realmente sobre o assunto.

Declare o escopo no relatório. Leia cada alegação que você vai alterar com knowledge_record e metadataView: "full". Seu subject_hint, quando presente, é a própria descrição do salvador sobre o que é a alegação e a pista mais forte para seu assunto. Agrupe as alegações pelo que elas são sobre (uma funcionalidade, PR, commit, thread de decisão, pessoa ou preferência) antes de escolher páginas. A maioria das alegações faz sentido apenas ao lado de suas vizinhas: uma série de instantâneos de estado sobre um PR geralmente termina em uma alegação de resultado.

2. Escolha páginas de assunto

Para cada grupo, encontre páginas candidatas com knowledge_grep e knowledge_lookup, e leia seu Estado. Ignore páginas retiradas e páginas de fixture.

• O assunto principal é sobre o que a alegação afirma algo; liste-o primeiro em entities. Adicione um assunto secundário apenas quando a alegação também afirma algo sobre essa entidade, como a pessoa que tomou a decisão ou a empresa cujo produto foi configurado. Uma menção passageira não é um assunto. Dois ou três assuntos geralmente são suficientes.
• O assunto principal é a página mais específica sobre a qual a alegação é: uma alegação sobre um PR pertence à página desse PR, não apenas ao projeto ao qual o PR pertence. A página mais ampla permanece um assunto apenas quando a alegação diz algo sobre ela, como uma decisão, política ou lançamento em nível de projeto.
• Uma preferência ou decisão declarada por uma pessoa pertence à página dessa pessoa. Não transforme a preferência de uma pessoa em uma política de projeto ou empresa.
• Combine identidade com base em evidências, não em nomes semelhantes. Quando uma alegação nomeia algo que pode ser uma página existente (por exemplo, um nome de produto que poderia ser um serviço diferente), confirme a partir de evidências como configuração, uma URL ou os próprios aliases da página. Se permanecer incerto, deixe a alegação onde está e relate.

Vincule com knowledge_annotate entities, passando a lista completa (ela substitui a existente) e a revisão e hash atuais da alegação. Texto de asserção, evidência e ciclo de vida permanecem inalterados. Vincule uma alegação antes de substituí-la: alegações substituídas não podem ser re-vinculadas.

3. Crie páginas faltantes e re-vinculá-las

Vincular cada alegação à página existente mais próxima pode enterrar um assunto real em uma página ampla. Crie uma página quando:

• um assunto discreto (uma funcionalidade, projeto, ferramenta ou PR substancial) tem aproximadamente cinco ou mais alegações, ou tem seu próprio design, prova e histórico de resultado; ou
• uma pessoa ou organização autora, possui ou decidiu algo nas alegações, não tem página e tem evidência de identidade (por exemplo, o autor do PR mostrado por gh pr view).

Não crie uma página para uma única menção ou uma correção pontual que uma alegação datada cobre. Use knowledge_save_page com o tipo de ontologia, aliases e a evidência de identidade como source. Páginas de pessoa usam identity.status: partial a menos que a identidade esteja totalmente estabelecida. Escreva um Estado curto que cite as alegações; sua Linha do Tempo é derivada delas. Vincule a nova página de sua página pai.

Em seguida, re-vincule as alegações do grupo, incluindo os instantâneos que o passo 4 substituirá. A nova página se torna o assunto principal de cada alegação. Mantenha a página ampla na qual as alegações foram arquivadas (geralmente o hub a partir do qual esta revisão começou) apenas para alegações que dizem algo sobre ela, pela regra do passo 2; remova-a do resto. Mantenha outros assuntos secundários existentes que ainda se qualificam. Abaixo do limite, deixe as alegações em suas páginas atuais.

4. Retire duplicatas, alegações substituídas e séries de instantâneos

• Duplicata: duas alegações afirmam o mesmo fato, decisão ou preferência sobre o mesmo evento. Mantenha a que tem recall aprovado pelo proprietário, caso contrário a mais antiga, caso contrário a que tem atribuição mais completa. Copie qualquer evidência que o sobrevivente não tenha com knowledge_annotate addEvidence, depois knowledge_withdraw a outra com um motivo que nomeie o ID do sobrevivente.
• Substituída: uma alegação posterior corrige explicitamente a anterior (por exemplo, um assistente corrigindo seu próprio relatório) ou decide uma questão que a alegação anterior deixou em aberto. Substitua a alegação anterior pela posterior com knowledge_supersede, com um motivo que diga o que a substituiu. Não use knowledge_correct aqui: ele publica uma nova cópia da substituição, o que cria outra duplicata.
• Série de instantâneos: vários instantâneos de estado sobre um item específico (o mesmo PR, commit ou thread de decisão: CI vermelho em uma cabeça, revisão solicitada, CI verde) seguidos por uma alegação de resultado sobre o mesmo item (mesclado, fechado, revertido, lançado, decidido, abandonado). Substitua cada instantâneo na série pelo resultado em uma chamada knowledge_supersede (até 25 alegações). Todos estes devem ser verdadeiros, a partir do próprio texto e datas das alegações:
  • cada instantâneo e o resultado nomeiam o mesmo item específico, não meramente o mesmo projeto;
  • o resultado é datado após cada instantâneo que substitui e declara um estado final, não outro intermediário;
  • o resultado e os instantâneos compartilham uma página de assunto (vincule-os primeiro, passo 3); a ferramenta rejeita alegações sem uma página comum. Um instantâneo datado após o resultado, ou um sobre uma cabeça diferente ou um item diferente, permanece.
• Nenhum dos dois: instantâneos de momentos diferentes que nenhum resultado posterior substitui (CI vermelho, depois CI verde, sem mesclagem ainda) são história, não erros. Mantenha-os. Contradição sozinha não justifica uma retirada ou uma substituição. Quando estiver em dúvida, mantenha ambos e relate o par.

knowledge_supersede mantém o texto, evidência, proveniência e histórico de cada alegação substituída, registra superseded_by e o motivo nela, e deixa a alegação substituidora inalterada. Leituras padrão param de mostrar alegações substituídas; leituras históricas (historical: true, lifecycle: "all") e knowledge_history ainda mostram. Se uma substituição estiver errada, chame-a novamente com undo: true, a mesma alegação by e as cercas de seu recibo items.

5. Atualize a prosa da página

Vincular torna as alegações acessíveis a partir de suas páginas; não altera o que uma página diz. Edite uma página apenas quando as alegações mudam seu estado durável: uma decisão, uma preferência, uma alteração implementada ou lançada, uma nova capacidade, uma questão em aberto resolvida ou texto de página que alegações posteriores mostram estar errado.

• Colapse uma série de instantâneos de progresso em seu resultado. Instantâneos (execuções de CI, PRs abertos, commits locais) são no máximo alegações de eventos datados, nunca Estado.
• Verifique o estado mutável ao vivo antes de escrevê-lo como atual (por exemplo, gh pr view para estado de mesclagem) e diga quando você verificou. Uma mesclagem não é uma implantação, e uma implantação não é prova de que um determinado Gateway executa o código.
• Quando uma página de design ou decisão contradiz uma decisão posterior, adicione uma emenda datada ao lado do texto original em vez de reescrevê-lo. Marque perguntas em aberto respondidas como resolvidas e mantenha a pergunta original.
• Cite cada frase adicionada com links [[claim-id|label]] para as alegações.
• Os corpos das páginas têm um orçamento de tamanho (orçamentos de página). Uma edição state: "rejected" não salvou nada, mas as alegações vinculadas já contêm os fatos. Mova uma seção para a página de seu assunto com knowledge_extract_section (criando a página conforme o passo 3 quando necessário), releia e tente novamente. Nunca encurte outra prosa para abrir espaço. A extração torna o destino o primeiro assunto das alegações que a seção cita e mantém seus assuntos existentes, incluindo a página da qual você extraiu. Aplique o passo 2 a cada uma dessas alegações e remova a página de origem com knowledge_annotate entities onde a alegação não diz nada sobre ela.

Use knowledge_edit_body para edições de seção. Calcule deslocamentos UTF-16 a partir de uma leitura completa recente, e releia a revisão e o hash antes de cada edição: outras sessões editam páginas ocupadas simultaneamente. Prefira inserir texto em vez de substituí-lo. Substitua uma seção inteira de Estado apenas quando tudo estiver desatualizado e mantenha os links de alegação que ela já tinha.

6. Verifique e relate

Execute knowledge_verify com expectedEntities para cada alegação vinculada e expectedLinks para cada página nova ou editada. Enumere o escopo novamente: novas alegações podem ter chegado enquanto você trabalhava. Lide com elas da mesma forma ou relate-as.

Relate o escopo, o número de alegações examinadas, vinculadas e re-vinculadas, páginas criadas, alegações substituídas (com a alegação substituidora para cada série), alegações retiradas (com a alegação sobrevivente para cada), páginas editadas e alegações deixadas inalteradas que você considerou, com o motivo de cada. Ao executar sem supervisão, nunca peça uma decisão e nunca adivinhe: deixe identidades incertas, duplicatas incertas, séries de instantâneos cujo resultado não é certo e páginas que você só criaria com base em um palpite intocados, e liste-os no relatório para uma pessoa.

Execuções do escriba

O escriba Consolidação de Conhecimento executa esta revisão sem supervisão sobre o resíduo não vinculado, no cronograma em seu prompt. Seu prompt verifica o acesso e configura sua automação; esta seção é apenas o trabalho de uma execução.

• Execute o passo 1 para o resíduo não vinculado. Quando o resíduo estiver vazio, relate zero alegações examinadas e prossiga para as Linhas do Tempo escritas abaixo.
• Caso contrário, trabalhe nos passos 2 a 6 e verifique o resíduo novamente antes de parar, pois alegações salvas durante a execução fazem parte do mesmo backlog.
• Em seguida, retire até 10 seções ## Linha do Tempo escritas, as maiores primeiro (retirar uma Linha do Tempo escrita). Encontre-as com knowledge_grep para Timeline e confirme o cabeçalho no corpo da página. Conte as seções retiradas e as páginas que ainda carregam uma.
• Não faça perguntas. Dê o relatório do passo 6; a linha de status de fechamento conta as alegações examinadas, vinculadas, substituídas, retiradas e deixadas, depois Linhas do Tempo retiradas e deixadas.