evlog Content Writing

Writing evlog content

Everything needed to draft or judge evlog prose. Two roles use this skill and they must not be merged.

Review produces findings and a verdict. It never rewrites, never softens, never proposes wording. Rewrite applies findings. It touches only what a finding names, and cites the rule or tell id for every change.

Splitting them is what keeps the loop honest. A reviewer that can rewrite talks itself into changes it cannot justify, and a rewriter that can re-judge its own output always passes.

Structure

references/
  voice.md        the voice and the five tests. Load first, always
  rules/          atomic rules, one file per surface group
    universal.md    every surface
    docs.md         apps/docs/content
    blog.md         blog posts
    landing.md      0.landing.md and other marketing surfaces
    machine.md      skills and AGENTS.md, the surfaces an agent acts on
  ai-tells.md     the tell corpus, each tell with its legitimate twin
  terminology.md  the names evlog gave its own parts (U-15)
  landscape/      what pino, winston, consola, and OpenTelemetry actually do (U-12)
  surfaces/       what each surface owes its reader
    docs.md  blog.md  landing.md  readme.md  skill.md  agents.md  changeset.md
  samples.md      evlog pages that read right, and why. What the tells must not flag
  corrections.md  accumulated lessons from rejected rewrites. Grows over time

Load voice.md first. Then the rule file for the surface, ai-tells.md when reviewing, and the matching surfaces/ file when drafting. Open terminology.md when a U-15 candidate is in play and the relevant landscape/ dossier before writing any sentence that names another logger. Do not load everything.

The corpus

Everything evlog ships as prose, on both sides of the line:

The house rules cross the line: punctuation, terminology, accuracy, dead links. Rhythm does not. A skill whose four steps read as four parallel imperatives is a procedure, and the scanner leaves rhythm alone there. See rules/machine.md.

One part of that table is excluded from the scan: this skill's own references/, because they quote the prose they ban, worked pair by worked pair, and scanning them measures the examples. The exclusion lives in scripts/content-lint/lib/surfaces.mjs, and it means the scanner will never tell you those files drifted. Read them yourself.

Evi's own trees used to sit outside the corpus too, so the scanner read everything but them while their prose accumulated em dashes for months. They are in now, and that history is the reason: a written surface the scanner cannot see is one that can drift forever. Findings on a skill surface come back as a report for a person to judge, never as a rewrite of the instructions the pass itself runs on.

Severity

• critical blocks publishing: a wrong code sample, a phantom API, a claim the source contradicts, a landing promise no page delivers.
• standard is fixed when the page is touched: voice, rhythm, structure, punctuation.

A tell about rhythm is never critical on its own. Epigram density, heading shape, bullet frames, and sentence uniformity describe how prose reads, and prose that reads a certain way has never broken anything.

Correctness takes precedence over the scan score. Verify behavioral claims against the relevant source revision, run examples presented as executable, and check that comparison sources support the exact claim and configuration. Dossiers are research starting points and can be wrong even when recently checked. Search for exceptions to absolute guarantees and check equivalent workloads before drawing benchmark conclusions. A factual fix remains necessary if its style score falls; judge the new candidates before changing the prose again.

Two entries in the tell corpus are not rhythm and do not follow that rule. T-15 is drift: a symbol or entry point the package does not export, which is a fact the source settles and always critical. T-13 is a house rule the maintainer decided, and one occurrence is a finding. They live in ai-tells.md because that is where the scanner's ids are documented, not because they are matters of taste.

Reviewing

Run the scanner first, always:

pnpm content:lint apps/docs/content/2.learn/2.wide-events.md --json

It returns per-page metrics, phrase hits, and API-drift findings. With no path it ranks the whole corpus worst-first, which is how a pass picks its target, and --surface narrows it to one kind of page:

pnpm content:lint --top 10
pnpm content:lint --surface skill --top 5
pnpm content:lint --url https://example.com/post --as blog   # a page outside the repo
cat draft.md | pnpm content:lint --stdin                     # prose that is not a file yet

Some findings are fixed before anyone reads them. pnpm content:lint <paths> --fix applies the rules whose corrected text follows from the rule itself: a retired entry point, a term with one replacement, a link with a redirect behind it. Punctuation is not among them, so every dash reaches you. It re-scans afterwards and reverts any file that scored worse or that introduced a finding id the page did not have, so a fix that trades one problem for another never lands. Run it before reviewing, so a review spends its attention on what a codemod cannot decide.

Rates are compared per surface. A reference page and a skill file have different natural rhythms, and one median over both flatters whichever is looser. A --url scan drops every evlog-specific check: someone else's entry points, links, and vocabulary are theirs, so what comes back is how the page reads.

Every scan returns two lists. The findings are what tripped a counter. modelChecks is what no counter reached on that page, chosen for its surface and its shape: whether the claims carry a mechanism, whether the opening states a situation, whether a skill's description would route to it, whether the code runs. Answer all of them. A review that only works the findings reviews only what was measurable, and a page can satisfy every count while answering nothing.

Then, in order:

1. Separate the rules from the rhythms. A house rule (U-14 punctuation, T-13 assistant framing, T-15 a retired entry point) is already decided: one occurrence is a finding. A rhythm (epigram density, uniform sentences, header lock) is a judgment call, and the scanner gives you the rate, not the answer.
2. Put every rhythm candidate next to its twin. Each tell in ai-tells.md ships Reads generated and Reads legitimate. Almost every one has a lawful twin in reference documentation: a required and optional field list is a complement set, three drains listed is a rule of three, uniform sentence length is the register of an API page. Say which side the candidate is nearer. If it is nearer the twin, drop it. If it genuinely sits between, keep it and name what made it survive.
3. Check it against samples.md. These are evlog pages that read right. The test that decides most borderline cases: does the line deliver a fact, a number, a mechanism, or a decision? A short closer that lands a measurement is voice. The same closer restating the paragraph is a tell.
4. Verify what the scanner flagged as drift. Every symbol in backticks that the scanner could not find in packages/evlog/src is either a doc that outran a rename or a false hit on prose. Read the source before writing the finding.
5. Check every comparison against its dossier. A U-12 candidate means a sentence claims something about pino, winston, consola, or OpenTelemetry with nothing behind it. Open landscape/<tool>.md. If the claim is not in the dossier, it is unverified, and unverified is a finding whether or not the claim is true.
6. Judge the structure yourself. Header template lock, paragraph-rhythm uniformity, and a page that never lets the reader do anything are invisible to a scanner.