Checked all 114 hits on the full docs/ tree by hand, not sampled: every
single one flags a precise, normal technical/formal word from
write-good's default corporate-bloat wordlist (validate, monitor,
therefore, however, multiple, additional, previously, subsequent,
equivalent, sufficient, exclusively, finalize, terminate, enumerate,
minimize, consolidate, eliminate, acquire, evaluate, satisfy,
implement, "it IS"/"it is"/"it was", "all of", "is responsible for",
"in addition"), not an actual verbose phrase. None of the genuinely
wordy multi-word bloat this rule exists to catch (due to the fact
that, in order to, at the present time, for the purpose of) appears
even once. Rewriting 114 instances of precise vocabulary into vaguer
prose to satisfy a dictionary mismatch would make the docs worse, not
better -- same shape as the Microsoft.Percentages/Microsoft.Dashes/
Microsoft.HeadingColons entries already in this file's "ruled on, not
wave 2" section.
Full evidence (the actual word/phrase breakdown, and why the 13
closest hits -- "it is"/"it was"/"all of"/"is responsible for"/"in
addition" -- were manually read in context and still don't count) was
already posted on hyperhive#4042; this just applies the conclusion.
Verified: nix shell nixpkgs#vale --command sh -c 'vale sync && vale
docs' before/after -- 908 -> 794 warnings (-114, exactly the disabled
rule's own hit count), 49 errors unchanged (all Microsoft.Avoid/
Contractions, unrelated to this rule), zero remaining TooWordy hits.
.vale.ini's own comments named the issues that gated
write-good.Passive, but the tracker-tag lint's extension list didn't
cover .ini, so it never caught its own violation. Extend the scope
and reword the comment to prose that stands on its own.
Both blockers are done — #4548 (353 hits in hand-written docs) and
#4549 (46 hits in generated CLI reference docs, hivectl/swarmctl/hive-forge's
own clap help text) — and the previous commit suppresses the reviewed
false-positive remainder. vale --minAlertLevel=error docs now returns
0 errors, matching CI's existing prose-lint-errors job.
Closes#4546.
HeadingColons conflicts with this repo's sentence-case heading
convention -- same shape as the existing Dashes disable, a house-style
conflict rather than a defect.
Percentages had zero true positives on the full docs/ tree: it only
ever fired on identifier uses of "percent" (cpu.percent, percent
resolver), never on an actual spelled-out percentage.
Plurals: rewrote the two real hits to always use the plural form
instead of the parenthetical (s) construction, per house style.
mara's review, addressed with evidence not assertions:
- Microsoft.Contractions: re-enabled per her flat disagreement, no
argument.
- Microsoft.Passive vs write-good.Passive: she asked what the
difference actually is. Ran both individually against the full
docs/ tree and diffed the exact file:line:col sets -- 726/726
identical, zero difference either direction. Genuinely redundant,
not assumed. write-good.Passive stays enabled (agreed base style),
Microsoft.Passive drops as the literal duplicate.
- write-good.Passive: she disputed my invented examples (correctly --
a clean single-actor rewrite does read better active). Pulled 10
real hits from the actual docs tree instead of inventing more
sentences; most have a generic/implicit actor where passive reads
naturally, not a clear active-voice win. Re-enabled per the
redundancy point above rather than disabled as "mostly noise".
- Microsoft.Dashes: same outcome (stays disabled, retrofitting ~2000
existing occurrences is out of scope here) but the reasoning was
wrong -- not a "deliberate convention", an incidental one nobody
chose. Rewritten.
- Microsoft.Adverbs, alex.ProfanityUnlikely, write-good.E-Prime,
Microsoft.HeadingAcronyms: moved to an explicit "wave 2 candidates"
section -- disabled for this rollout, not dismissed. Each needs a
real false-positive-rate pass or an actual rewrite pass through the
flagged instances before a permanent call.
- Dropped the .vale.ini header's pointer to "the PR description" for
rationale -- not durable/visible enough as a reference from a file
that lives in the repo. Rationale is now fully inline per rule.
1069 more hits than the previous round (726 write-good.Passive + 343
Contractions, Microsoft.Passive's 726 removed) -- 1732 total across 50
files.
