Skip to content

feat(docs): enable Coder.ImperativeNegation Vale rule - #30784

Closed
nickvigilante wants to merge 7 commits into
mainfrom
vigilante/docs-1262-add-coderimperativenegation-vale-rule-for-imperative-dont
Closed

nickvigilante wants to merge 7 commits into
mainfrom
vigilante/docs-1262-add-coderimperativenegation-vale-rule-for-imperative-dont

Conversation

@nickvigilante

Copy link
Copy Markdown
Collaborator

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.

  • 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

Decision log
  • 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.

Generated by Coder Agents on behalf of @nickvigilante.

Add the style rules from the Docs style guide Linear project that the
guide was missing, and fix the guide's own self-violations from the
second ASD-STE100 audit. Each new Vale rule lands in its own PR based
on this one, so every footer for those rules is marked planned.

The Vale doctrine now lets suggestion-level rules land with existing
findings, per Nick's decision on DOCS-450.

Refs DOCS-1282, DOCS-1265
@linear-code

linear-code Bot commented Oct 14, 2026

Copy link
Copy Markdown

DOCS-1262

@github-actions

github-actions Bot commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

Docs preview

Check off each page once it's been reviewed. If a page changes in a later push, its checkbox clears automatically so it gets a fresh look. Pages not yet wired into the docs navigation aren't listed here.

@nickvigilante
nickvigilante force-pushed the vigilante/docs-1262-add-coderimperativenegation-vale-rule-for-imperative-dont branch from 6ed2b4e to 4b944d1 Compare October 14, 2026 20:52
Base automatically changed from vigilante/docs-1282-style-guide-add-missing-rules-from-the-docs-style-guide to main October 16, 2026 13:53
Take main's style guide, which already carries the squashed docs
style guide rules, and reapply the ImperativeNegation footer,
checks-table row, coverage counts, and the "do not" cleanup on top
of main. The cloning-git-repositories page is now one sentence per
line on main, so the "Do not forget" fix is reapplied to that line.

Assisted-by: AI
@nickvigilante
nickvigilante marked this pull request as ready for review October 23, 2026 05:49
coder Bot pushed a commit that referenced this pull request Oct 23, 2026
Recreated from #30784 under coder[bot] so it can be reviewed by its requester. Stacked on #31183.
nickvigilante added a commit that referenced this pull request Oct 23, 2026
Recreated from #30784 under coder[bot] so it can be reviewed by its requester. Stacked on #31183.
nickvigilante added a commit that referenced this pull request Oct 23, 2026
> [!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>
@nickvigilante

Copy link
Copy Markdown
Collaborator Author

Superseded by #31184, which merged the same change into main as part of the stacked Vale rule PRs. Closing as a duplicate.

Generated by Coder Agents on behalf of @nickvigilante.

@github-actions github-actions Bot locked and limited conversation to collaborators Oct 24, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant