Metrics

A blueprint nobody finishes reading is worse than none. The Metrics plugin holds each blueprint to a reading budget, points out the text a reader skips, and counts what your root chooses to track. Every measure is deterministic and local: no model is called, and the same root gives the same figures and findings on every machine. Each finding is a warning, so it fails a run only where the root is strict. On for a root made from 0.14.0 on; eidos plugin enable metrics switches it on for an older one.

Reading time

Every blueprint shows how long it takes to read beside its path (“4 min read”, or “Under 1 min read”), in a modal and on its page, whatever plugins are on. It counts the author’s prose alone: the frontmatter, headings, fenced code, HTML comments, a tool’s regions, and any paragraph the blueprint’s template itself carries (an italic prompt, a default line) are left out, so a blueprint just scaffolded reads as empty. The pace is fixed and has no setting. eidos show --json and eidos list --json carry it as reading_time.

Each ## section is measured too, the sections under it included. A section only a tool writes, such as Tasks or a records list, is left out.

Budgets

A budget says how long a collection’s blueprints should take to read at most: all of them, one kind (a variant), or one ## section of their template by its heading. Give it in minutes, words, or both, where the stricter holds. A kind’s own budget wins over its collection’s. A minutes budget is the friendlier one: a spec should take five minutes to read.

A blueprint or section over its budget is metrics/over-budget, which says how long it takes and what to do: “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

What to trim

Three warnings point out text a reader skips. Each says what was found and what to do, and each can be switched off on its own.

Filler phrases (metrics/filler): a phrase from the root’s list, matched in any case as whole words and reported with its line: “Line 19: “in order to” is filler. Cut it, or say the thing plainly.” The list starts with a set of filler and hedge phrases (in order to, it is important to note, due to the fact that, and more), and is yours to edit on the settings page or with eidos metrics configure:filler add|remove <phrase>.
Repeated sentences (metrics/repeated-sentence): a sentence of six words or more said twice in one blueprint, reported where it is said again. A sentence wholly in parentheses, such as a citation, is not counted.
Copied paragraphs (metrics/near-duplicate): a paragraph nearly the same as one in another blueprint, reported in both, each naming the other: keep it in one place and link to it. How alike (70% by default) sets how much of two paragraphs must match, and Shortest paragraph (25 words) the shortest one compared.

Each reads the same prose the reading time does, so a template’s prompts and default lines are never reported. eidos plugin set metrics filler off switches one off (repeated-sentence, near-duplicate likewise).

Counts of your own

A root can count things of its own for each blueprint of a collection (all of its kinds, or one), with a least and a most. A count is one of four kinds, never a script:

words or read_time: of the blueprint, or of one ## section.
records: how many records the blueprint holds, from the Records plugin, of one type, and with fields at given values (--where status=Open).
filled: how much is filled in, as a percentage: a frontmatter property (100 or 0), or the share of a type’s records with a field filled.

A value under its least or over its most is metrics/threshold, naming the count, its value, and the bound: a spec of at most 1,500 words, every Character with an arc, no more than three open Hypotheses. With Records off, a records count has no value and never warns; the Metrics view says to turn Records on to count it.

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

In the browser

Metrics, a view in the Auxiliary Sidebar beside the open blueprint, headed by its title: the reading time and words on a bar against the budget (the accent within it; the warning colour and how far over past it), or Set a budget where there is none. Then Sections over budget, each with its figures, What you track, each count with its range and In range or Out of range, and To trim, a card per filler phrase, repeated sentence, or copied passage, quoting it with the advice and a Go to line N button that opens the blueprint at it.
The plugin’s settings page sets every one of them in words: Reading budgets as sentences (“Specs, full specs, the whole spec, should take at most 5 min to read or … words”), Things to count as lines (what to count, in which blueprints, and when to warn), and Filler and repetition, with a switch for each warning, the phrase list one phrase a line, How alike, and Shortest paragraph.

Simplifying with an agent

eidos instructions simplify is the guide an agent follows to propose cuts to a blueprint against its budget and its findings: each cut or merge a separate suggestion, with the passage quoted, its line, the proposed text, and the finding it answers. The agent changes nothing until you accept a suggestion, applies only what you accepted, and never raises a budget to clear a finding. A blueprint within its budget and with no finding gets no proposal.

On disk

.eidos/plugins/metrics/settings.yaml, shared: budgets (each { collection, variant?, section?, words?, minutes? }), metrics (the counts of your own), the switches filler, repeated-sentence, and near-duplicate, filler_phrases, near_duplicate_similarity, and near_duplicate_min_words. The settings page and the configure: commands write it; never edit it by hand.

The plugin keeps nothing else. Reading time is worked out from the blueprints each time.

From the shell

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 carries each blueprint’s reading_time, and under plugins.metrics whether it is over budget, its findings, and the value of each count by name.

What the check reports

All warnings: metrics/over-budget (a blueprint or section past its budget), metrics/filler, metrics/repeated-sentence, metrics/near-duplicate (reported in both blueprints), and metrics/threshold (a count of your own under its least or over its most). Off, the plugin measures nothing, and the reading time still shows on every blueprint.