Files
coder/docs/reference
coder[bot]andNick Vigilante 635a1a8a5f feat(docs): enable Coder.ImperativeNegation Vale rule (#31184)
> [!NOTE]
> Recreated from #30784 under coder[bot] by Superblink, at the request
of @nickvigilante, so he can review and merge it. An AI agent wrote the
original, which was opened from his account. The diff is identical to
#30784, squashed onto current `main`. Superblink reviewed it and ran
Vale over `docs/` before opening this PR (no new warnings or errors).
#30784 should be closed in favor of this one.
> Stack: based on #31183 (#31180 → #31181 → #31182 → #31183 → #31184 →
#31185). The diff matches #30784 except for the counters in
`docs/.style/style-guide/README.md`, which build on the PRs below this
one. `make lint/style-claims` passes at every level.

Depends on #30782.

Adds `Coder.ImperativeNegation`, a Vale rule that flags `don't` where it
opens an imperative and suggests `do not`.
It enforces [Spell out negative
instructions](https://github.com/coder/coder/blob/main/docs/.style/style-guide/voice-and-tone.md#spell-out-negative-instructions).

- Severity: `warning`.
- Scope: `docs/**` except `docs/.style/style-guide/**`, which
demonstrates the violations on purpose.
- Baseline: 14 findings in 9 files.
  The cleanup commit fixes all of them, so the rule ships at zero.
I also fixed one imperative the rule can't see (`**Link to their docs**,
don't duplicate` in `content-guidelines.md`).
- Generated reference pages: no findings, so no exclusion.
- Known gap: an imperative after a bare comma goes unreported.
Declaratives such as `Headings are sentence case, don't lead` share that
shape.

Linear: DOCS-1262

<details><summary>Decision log</summary>

- Boundary pattern, not a verb list. The rule matches `don't` (straight
or curly apostrophe) only after a paragraph start (`\A`), a sentence
end, a colon, a semicolon, or `, and`.
- Comma case. A bare `, don't` produced false positives (`Headings are
sentence case, don't lead`, `events..., such as updates, don't reach
clients`).
The rule instead requires a comma that closes an opening
`If`/`When`/`Before`/`After`/`Unless`/`Once`/`While`/`Until` clause with
no other comma in it.
- `\A` instead of `^`. `^` also matches at a hard-wrapped line start,
which flagged `usually\ndon't.` in `managing-templates/index.md`.
- Bold lead-ins (`**Note:** Don't`) work because Vale strips markup
before matching. Code spans are skipped.
- Table cells and blockquotes are in scope. One table cell and three
blockquote or list lines needed cleanup.
- `Don't know where to start?` is an elliptical question, so it became
`Not sure where to start?`.
- Only `don't` is in scope. `can't` and `won't` are rarely imperative.
- Link uses the GitHub blob form that the existing rules use.
- Enable commit also updates the checks table, the coverage counts
(Voice and tone 0/4 to 1/3, total 9 to 10 tool-checked and 33 to 32
planned), and the "What the tooling checks" counts.

Tests (fixtures in `/tmp`, not committed), each run with LF and CRLF
files:

- Flagged: paragraph-initial `Don't`, `Run it. Don't`, `, and don't`,
curly `If..., don’t`, `; don't`, `**Note:** Don't`, `: don't`, list
item, table cell, blockquote.
- Not flagged: `You don't need`, `Tools that don't`, `Coder won't push`,
`Headings are sentence case, don't lead`, `If X is blocked, Coder
doesn't..., so events, such as updates, don't reach`, a hard-wrapped
line starting with `don't`, and `` `don't` `` in a code span.
- `vale --output=line docs/`: 0 `Coder.ImperativeNegation` findings
outside the style guide.
- `go run ./scripts/styleclaims`, `make lint/emdash`, and the pre-commit
hook (markdown, typos, style-claims) pass.

</details>

*Generated by [Coder Agents](https://coder.com/docs/ai-coder/agents) on
behalf of @nickvigilante.*

Created on behalf of @nickvigilante

Co-authored-by: Nick Vigilante <nick.vigilante@coder.com>
2026-10-23 16:36:44 +00:00
..