Repository navigation
feat(docs): enable Coder.ImperativeNegation Vale rule - #30784
Closed
nickvigilante wants to merge 7 commits into
Closed
nickvigilante wants to merge 7 commits into
nickvigilante wants to merge 7 commits into
Conversation
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
Contributor
Docs previewCheck 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
force-pushed
the
vigilante/docs-1262-add-coderimperativenegation-vale-rule-for-imperative-dont
branch
from
October 14, 2026 20:52
6ed2b4e to
4b944d1
Compare
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
marked this pull request as ready for review
October 23, 2026 05:49
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>
Collaborator
Author
|
Superseded by #31184, which merged the same change into Generated by Coder Agents on behalf of @nickvigilante. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Depends on #30782.
Adds
Coder.ImperativeNegation, a Vale rule that flagsdon'twhere it opens an imperative and suggestsdo not.It enforces Spell out negative instructions.
warning.docs/**exceptdocs/.style/style-guide/**, which demonstrates the violations on purpose.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 duplicateincontent-guidelines.md).Declaratives such as
Headings are sentence case, don't leadshare that shape.Linear: DOCS-1262
Decision log
don't(straight or curly apostrophe) only after a paragraph start (\A), a sentence end, a colon, a semicolon, or, and., don'tproduced 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/Untilclause with no other comma in it.\Ainstead of^.^also matches at a hard-wrapped line start, which flaggedusually\ndon't.inmanaging-templates/index.md.**Note:** Don't) work because Vale strips markup before matching. Code spans are skipped.Don't know where to start?is an elliptical question, so it becameNot sure where to start?.don'tis in scope.can'tandwon'tare rarely imperative.Tests (fixtures in
/tmp, not committed), each run with LF and CRLF files:Don't,Run it. Don't,, and don't, curlyIf..., don’t,; don't,**Note:** Don't,: don't, list item, table cell, blockquote.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 withdon't, and`don't`in a code span.vale --output=line docs/: 0Coder.ImperativeNegationfindings 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.