Metrics

Un Blueprint (el plano) que nadie termina de leer es peor que ninguno. El plugin Metrics ajusta cada Blueprint a un presupuesto de lectura, señala el texto que un lector se salta y cuenta lo que tu raíz decide seguir. Cada medida es determinista y local: no se llama a ningún modelo, y la misma raíz da las mismas cifras y los mismos hallazgos en cualquier máquina. Cada hallazgo es un aviso, así que solo hace fallar una ejecución donde la raíz es estricta. Activo en una raíz creada desde 0.14.0; eidos plugin enable metrics lo activa en una más antigua.

Tiempo de lectura

Cada Blueprint muestra cuánto se tarda en leer junto a su ruta (“4 min read”, o “Under 1 min read”), en un modal y en su página, estén activos los plugins que estén. Cuenta solo la prosa del autor: el frontmatter, los encabezados, el código entre vallas, los comentarios HTML, las regiones de una herramienta y cualquier párrafo que traiga la propia plantilla del Blueprint (una indicación en cursiva, una línea por defecto) quedan fuera, así que un Blueprint recién creado se lee como vacío. El ritmo es fijo y no tiene ajuste. eidos show --json y eidos list --json lo llevan como reading_time.

Cada sección ## también se mide, con las secciones que tiene debajo. Una sección que solo escribe una herramienta, como Tasks o una lista de registros, queda fuera.

Presupuestos

Un presupuesto dice cuánto deberían tardar como mucho en leerse los Blueprints de una colección: todos, los de una variante, o una sección ## de su plantilla por su encabezado. Dalo en minutos, en palabras o en ambos, y rige el más estricto. El presupuesto propio de una variante gana al de su colección. Un presupuesto en minutos es el más cómodo: una especificación debería leerse en cinco minutos.

Un Blueprint o una sección por encima de su presupuesto es metrics/over-budget, que dice cuánto tarda y qué hacer: “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

Qué recortar

Tres avisos señalan el texto que un lector se salta. Cada uno dice qué encontró y qué hacer, y cada uno se puede desactivar por separado.

• Frases de relleno (metrics/filler): una frase de la lista de la raíz, encontrada sin importar mayúsculas como palabras completas e informada con su línea. La lista empieza con un conjunto de frases de relleno y de cautela (in order to, it is important to note, due to the fact that y más) y es tuya para editar, en la página de ajustes o con eidos metrics configure:filler add|remove <phrase>.
• Frases repetidas (metrics/repeated-sentence): una frase de seis palabras o más dicha dos veces en un Blueprint, informada donde se repite. Una frase entera entre paréntesis, como una cita, no cuenta.
• Párrafos copiados (metrics/near-duplicate): un párrafo casi igual a uno de otro Blueprint, informado en los dos, cada uno nombrando al otro: déjalo en un solo sitio y enlázalo. How alike (70% por defecto) fija cuánto de dos párrafos debe coincidir, y Shortest paragraph (25 palabras) el párrafo más corto que se compara.

Cada uno lee la misma prosa que el tiempo de lectura, así que las indicaciones y las líneas por defecto de una plantilla nunca se informan. eidos plugin set metrics filler off desactiva uno (repeated-sentence y near-duplicate igual).

Recuentos propios

Una raíz puede contar cosas propias en cada Blueprint de una colección (de todas sus variantes, o de una), con un mínimo y un máximo. Un recuento es de una de cuatro clases, nunca un script:

• words o read_time: del Blueprint, o de una sección ##.
• records: cuántos registros tiene el Blueprint, del plugin Records, de un tipo y con campos en ciertos valores (--where status=Open).
• filled: cuánto está relleno, como porcentaje: una propiedad del frontmatter (100 o 0), o la parte de los registros de un tipo con un campo relleno.

Un valor por debajo de su mínimo o por encima de su máximo es metrics/threshold, que nombra el recuento, su valor y el límite: una especificación de 1.500 palabras como mucho, cada Character con su arco, no más de tres Hypotheses abiertas. Con Records desactivado, un recuento de registros no tiene valor y nunca avisa; la vista Metrics dice que actives Records para contarlo.

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

En el navegador

• Metrics, una vista en la barra lateral auxiliar junto al Blueprint abierto, encabezada por su título: el tiempo de lectura y las palabras en una barra frente al presupuesto (en el color de acento dentro de él; en el color de aviso y cuánto se pasa, por encima), o Set a budget donde no hay ninguno. Después Sections over budget, cada una con sus cifras, What you track, cada recuento con su rango e In range u Out of range, y To trim, una tarjeta por frase de relleno, frase repetida o pasaje copiado, que lo cita con el consejo y un botón Go to line N que abre el Blueprint ahí.
• La página de ajustes del plugin fija cada uno con palabras: Reading budgets como frases (“Specs, full specs, the whole spec, should take at most 5 min to read or … words”), Things to count como líneas (qué contar, en qué Blueprints y cuándo avisar), y Filler and repetition, con un interruptor por aviso, la lista de frases una por línea, How alike y Shortest paragraph.

Simplificar con un agente

eidos instructions simplify es la guía que sigue un agente para proponer recortes a un Blueprint frente a su presupuesto y sus hallazgos: cada recorte o fusión, una sugerencia aparte, con el pasaje citado, su línea, el texto propuesto y el hallazgo al que responde. El agente no cambia nada hasta que aceptas una sugerencia, aplica solo lo aceptado y nunca sube un presupuesto para quitar un hallazgo. Un Blueprint dentro de su presupuesto y sin hallazgos no recibe propuesta.

En disco

• .eidos/plugins/metrics/settings.yaml, compartido: budgets (cada uno { collection, variant?, section?, words?, minutes? }), metrics (los recuentos propios), los interruptores filler, repeated-sentence y near-duplicate, filler_phrases, near_duplicate_similarity y near_duplicate_min_words. Lo escriben la página de ajustes y los comandos configure:; nunca lo edites a mano.

El plugin no guarda nada más. El tiempo de lectura se calcula a partir de los Blueprints cada vez.

Desde la 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 lleva el reading_time de cada Blueprint y, bajo plugins.metrics, si pasa de su presupuesto, sus hallazgos y el valor de cada recuento por nombre.

Qué informa la comprobación

Todo son avisos: metrics/over-budget (un Blueprint o una sección por encima de su presupuesto), metrics/filler, metrics/repeated-sentence, metrics/near-duplicate (informado en los dos Blueprints) y metrics/threshold (un recuento propio por debajo de su mínimo o por encima de su máximo). Desactivado, el plugin no mide nada, y el tiempo de lectura sigue apareciendo en cada Blueprint.