write-good suggestions fail the prose check in CI

By Daniel Zoghalchali·Latchkey

write-good scans prose for passive voice, wordy phrases, weasel words, and cliches, and returns suggestions. When wired to fail on any hit, ordinary technical writing breaks the build even though the advice is stylistic.

What this error means

The docs job fails with write-good output such as "'is used' may be passive voice" or "'very' is a weasel word", pointing at line and column in a Markdown file.

docs/intro.md
"utilized" is wordy or unneeded on line 8 at column 12
"is generated" may be passive voice on line 14 at column 3

Common causes

The check gates on stylistic suggestions

write-good returns advice, not errors. Failing CI on every suggestion makes normal prose break the build.

Checks are enabled that do not fit technical docs

Passive voice and "so"/"there is" checks fire heavily in reference material where they are acceptable.

How to fix it

Disable checks that do not fit and gate loosely

Turn off noisy checks (passive, so) and treat write-good as advisory in CI rather than blocking.

// .write-good.json (via a runner that reads options)
{
  "passive": false,
  "so": false,
  "weasel": true
}

Run write-good through Vale for severity control

Vale bundles a write-good style and lets you set each rule to suggestion or warning so nothing fails the build unintentionally.

[*.md]
BasedOnStyles = write-good
write-good.Passive = suggestion

How to prevent it

• Treat readability linters as advisory, not blocking, in CI.
• Disable checks (passive, so) that do not fit technical reference docs.
• Run write-good via Vale so you control per-rule severity.

Frequently asked questions

Related guides

References

• GitHub Actions documentation