Metrics

Um Blueprint (o plano) que ninguém termina de ler é pior que nenhum. O plugin Metrics mantém cada Blueprint dentro de um orçamento de leitura, aponta o texto que um leitor pula e conta o que a sua raiz decide acompanhar. Cada medida é determinística e local: nenhum modelo é chamado, e a mesma raiz dá os mesmos números e os mesmos achados em qualquer máquina. Cada achado é um aviso, então só faz uma execução falhar onde a raiz é estrita. Ligado em uma raiz criada a partir da 0.14.0; eidos plugin enable metrics o liga em uma mais antiga.

Tempo de leitura

Cada Blueprint mostra quanto tempo leva para ser lido ao lado do seu caminho (“4 min read”, ou “Under 1 min read”), em um modal e na sua página, quaisquer que sejam os plugins ligados. Ele conta só a prosa do autor: o frontmatter, os cabeçalhos, o código cercado, os comentários HTML, as regiões de uma ferramenta e qualquer parágrafo que o próprio modelo do Blueprint traga (uma instrução em itálico, uma linha padrão) ficam de fora, então um Blueprint recém-criado é lido como vazio. O ritmo é fixo e não tem configuração. eidos show --json e eidos list --json o levam como reading_time.

Cada seção ## também é medida, com as seções abaixo dela. Uma seção que só uma ferramenta escreve, como Tasks ou uma lista de registros, fica de fora.

Orçamentos

Um orçamento diz quanto tempo, no máximo, os Blueprints de uma coleção devem levar para ser lidos: todos, os de uma variante, ou uma seção ## do seu modelo pelo cabeçalho. Dê em minutos, em palavras ou nos dois, e vale o mais estrito. O orçamento próprio de uma variante vence o da sua coleção. Um orçamento em minutos é o mais fácil: uma especificação deve ser lida em cinco minutos.

Um Blueprint ou uma seção acima do seu orçamento é metrics/over-budget, que diz quanto tempo leva e o que fazer: “This spec takes 10 min to read (2,232 words); its budget is 5 min of reading. Cut it down, or move detail into a spec of its own.”

eidos metrics configure:budget set specs --minutes 5                      # every spec
eidos metrics configure:budget set specs --variant full --minutes 8       # full specs only
eidos metrics configure:budget set specs --section Intent --words 150     # one section of every spec

O que cortar

Três avisos apontam o texto que um leitor pula. Cada um diz o que encontrou e o que fazer, e cada um pode ser desligado sozinho.

• Frases de enchimento (metrics/filler): uma frase da lista da raiz, encontrada sem diferenciar maiúsculas como palavras inteiras e relatada com a sua linha. A lista começa com um conjunto de frases de enchimento e de rodeio (in order to, it is important to note, due to the fact that e outras) e é sua para editar, na página de configurações ou com eidos metrics configure:filler add|remove <phrase>.
• Frases repetidas (metrics/repeated-sentence): uma frase de seis palavras ou mais dita duas vezes em um Blueprint, relatada onde se repete. Uma frase inteira entre parênteses, como uma citação, não conta.
• Parágrafos copiados (metrics/near-duplicate): um parágrafo quase igual a um de outro Blueprint, relatado nos dois, cada um nomeando o outro: deixe-o em um só lugar e faça um link para ele. How alike (70% por padrão) define quanto de dois parágrafos precisa coincidir, e Shortest paragraph (25 palavras) o parágrafo mais curto comparado.

Cada um lê a mesma prosa que o tempo de leitura, então as instruções e as linhas padrão de um modelo nunca são relatadas. eidos plugin set metrics filler off desliga um (repeated-sentence e near-duplicate da mesma forma).

Contagens próprias

Uma raiz pode contar coisas próprias em cada Blueprint de uma coleção (de todas as suas variantes, ou de uma), com um mínimo e um máximo. Uma contagem é de um de quatro tipos, nunca um script:

• words ou read_time: do Blueprint, ou de uma seção ##.
• records: quantos registros o Blueprint tem, do plugin Records, de um tipo e com campos em certos valores (--where status=Open).
• filled: quanto está preenchido, como porcentagem: uma propriedade do frontmatter (100 ou 0), ou a parte dos registros de um tipo com um campo preenchido.

Um valor abaixo do seu mínimo ou acima do seu máximo é metrics/threshold, que nomeia a contagem, o seu valor e o limite: uma especificação de no máximo 1.500 palavras, cada Character com o seu arco, não mais que três Hypotheses abertas. Com o Records desligado, uma contagem de registros não tem valor e nunca avisa; a visão Metrics diz para ligar o Records para contá-la.

eidos metrics configure:metric add spec-length --collection specs --measure words --max 1500
eidos metrics configure:metric add arcs --collection chapters --measure filled --record-type character --field arc --min 100
eidos metrics configure:metric add open-hypotheses --collection investigations --measure records --record-type hypothesis --where status=open --max 3

No navegador

• Metrics, uma visão na barra lateral auxiliar ao lado do Blueprint aberto, encabeçada pelo seu título: o tempo de leitura e as palavras em uma barra frente ao orçamento (na cor de destaque dentro dele; na cor de aviso e quanto passou, acima dele), ou Set a budget onde não há nenhum. Depois Sections over budget, cada uma com os seus números, What you track, cada contagem com a sua faixa e In range ou Out of range, e To trim, um cartão por frase de enchimento, frase repetida ou trecho copiado, que o cita com o conselho e um botão Go to line N que abre o Blueprint ali.
• A página de configurações do plugin define cada um em palavras: Reading budgets como frases (“Specs, full specs, the whole spec, should take at most 5 min to read or … words”), Things to count como linhas (o que contar, em quais Blueprints e quando avisar), e Filler and repetition, com um interruptor por aviso, a lista de frases uma por linha, How alike e Shortest paragraph.

Simplificar com um agente

eidos instructions simplify é o guia que um agente segue para propor cortes em um Blueprint frente ao seu orçamento e aos seus achados: cada corte ou junção, uma sugestão separada, com o trecho citado, a sua linha, o texto proposto e o achado a que responde. O agente não muda nada até você aceitar uma sugestão, aplica só o que foi aceito e nunca aumenta um orçamento para tirar um achado. Um Blueprint dentro do orçamento e sem achados não recebe proposta.

Em disco

• .eidos/plugins/metrics/settings.yaml, compartilhado: budgets (cada um { collection, variant?, section?, words?, minutes? }), metrics (as contagens próprias), os interruptores filler, repeated-sentence e near-duplicate, filler_phrases, near_duplicate_similarity e near_duplicate_min_words. A página de configurações e os comandos configure: o escrevem; nunca o edite à mão.

O plugin não guarda mais nada. O tempo de leitura é calculado a partir dos Blueprints a cada vez.

Pelo terminal

eidos metrics                                       # every blueprint: reading time, words, budget, findings
eidos metrics B-SHS2                                # one blueprint, section by section, with its counts and findings; --json
eidos metrics configure:budget set specs --minutes 5   # set|remove|list; --variant, --section, --words, --dry-run, --json
eidos metrics configure:metric add spec-length --collection specs --measure words --max 1500   # add|set|remove|list
eidos metrics configure:filler add "going forward"   # add|remove
eidos plugin set metrics near-duplicate off         # switch a warning off
eidos instructions simplify                         # the agent's guide to proposing cuts

eidos list --json leva o reading_time de cada Blueprint e, sob plugins.metrics, se ele passa do orçamento, os seus achados e o valor de cada contagem por nome.

O que a verificação relata

Tudo são avisos: metrics/over-budget (um Blueprint ou uma seção acima do orçamento), metrics/filler, metrics/repeated-sentence, metrics/near-duplicate (relatado nos dois Blueprints) e metrics/threshold (uma contagem própria abaixo do mínimo ou acima do máximo). Desligado, o plugin não mede nada, e o tempo de leitura continua aparecendo em cada Blueprint.