From b08dab37a460476c06c3e7372c11384b709115fc Mon Sep 17 00:00:00 2001
From: hilram7 <212961752+hilram7@users.noreply.github.com>
Date: Tue, 14 Apr 2026 15:58:49 -0400
Subject: [PATCH] Add local Vale KB style rules (NetwrixKB)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Create .vale/styles/NetwrixKB/ with eight rules scoped to KB articles,
and activate the style for docs/kb/**/*.md in .vale.ini.

Two rules are KB-specific:
- Contractions: flags contractions (don't, can't, it's, etc.) and prompts
  writing them out in full, the opposite of the existing Netwrix.Contractions rule
- HeadingCase: enforces Chicago-style title case for headings

Six rules are adapted from the Netwrix style: FirstPersonPlural, Please,
NoteThat, WeakLinkText, ImpersonalFiller, Utilize.

The docs/kb/**/*.md section previously had BasedOnStyles = (empty), which
disabled all Vale checking on KB files. KB files now receive NetwrixKB rules
only — the Netwrix style is intentionally excluded to avoid the contractions
conflict (Netwrix promotes contractions; KB requires writing them out in full).

TSEs can run 'vale <kb-file>' locally for KB-specific feedback.
---
 .vale.ini                                    |  2 +-
 .vale/styles/NetwrixKB/Contractions.yml      | 32 ++++++++++++++++++++
 .vale/styles/NetwrixKB/FirstPersonPlural.yml | 10 ++++++
 .vale/styles/NetwrixKB/HeadingCase.yml       |  6 ++++
 .vale/styles/NetwrixKB/ImpersonalFiller.yml  | 18 +++++++++++
 .vale/styles/NetwrixKB/NoteThat.yml          |  7 +++++
 .vale/styles/NetwrixKB/Please.yml            |  7 +++++
 .vale/styles/NetwrixKB/Utilize.yml           | 13 ++++++++
 .vale/styles/NetwrixKB/WeakLinkText.yml      | 10 ++++++
 9 files changed, 104 insertions(+), 1 deletion(-)
 create mode 100644 .vale/styles/NetwrixKB/Contractions.yml
 create mode 100644 .vale/styles/NetwrixKB/FirstPersonPlural.yml
 create mode 100644 .vale/styles/NetwrixKB/HeadingCase.yml
 create mode 100644 .vale/styles/NetwrixKB/ImpersonalFiller.yml
 create mode 100644 .vale/styles/NetwrixKB/NoteThat.yml
 create mode 100644 .vale/styles/NetwrixKB/Please.yml
 create mode 100644 .vale/styles/NetwrixKB/Utilize.yml
 create mode 100644 .vale/styles/NetwrixKB/WeakLinkText.yml

diff --git a/.vale.ini b/.vale.ini
index f1f6eb9254..7ba971d191 100644
--- a/.vale.ini
+++ b/.vale.ini
@@ -5,4 +5,4 @@ MinAlertLevel = suggestion
 BasedOnStyles = Netwrix
 
 [docs/kb/**/*.md]
-BasedOnStyles =
+BasedOnStyles = NetwrixKB
diff --git a/.vale/styles/NetwrixKB/Contractions.yml b/.vale/styles/NetwrixKB/Contractions.yml
new file mode 100644
index 0000000000..b14cbdad6d
--- /dev/null
+++ b/.vale/styles/NetwrixKB/Contractions.yml
@@ -0,0 +1,32 @@
+extends: existence
+message: "Write '%s' out in full for KB articles (e.g., 'do not', 'cannot', 'you will')."
+level: warning
+ignorecase: true
+tokens:
+  - "don't"
+  - "doesn't"
+  - "didn't"
+  - "can't"
+  - "wouldn't"
+  - "shouldn't"
+  - "couldn't"
+  - "isn't"
+  - "aren't"
+  - "wasn't"
+  - "weren't"
+  - "hasn't"
+  - "haven't"
+  - "hadn't"
+  - "you'll"
+  - "it's"
+  - "there's"
+  - "that's"
+  - "won't"
+  - "we're"
+  - "they're"
+  - "you're"
+  - "he's"
+  - "she's"
+  - "we've"
+  - "they've"
+  - "you've"
diff --git a/.vale/styles/NetwrixKB/FirstPersonPlural.yml b/.vale/styles/NetwrixKB/FirstPersonPlural.yml
new file mode 100644
index 0000000000..475707f49e
--- /dev/null
+++ b/.vale/styles/NetwrixKB/FirstPersonPlural.yml
@@ -0,0 +1,10 @@
+extends: existence
+message: "Avoid first person plural '%s'. Rewrite without 'we', 'our', 'us', or 'ours'."
+level: warning
+ignorecase: true
+nonword: true
+tokens:
+  - '\bwe\b'
+  - '\bour\b'
+  - '\bours\b'
+  - '\bus\b'
diff --git a/.vale/styles/NetwrixKB/HeadingCase.yml b/.vale/styles/NetwrixKB/HeadingCase.yml
new file mode 100644
index 0000000000..edf715228a
--- /dev/null
+++ b/.vale/styles/NetwrixKB/HeadingCase.yml
@@ -0,0 +1,6 @@
+extends: capitalization
+message: "Use title case for KB article headings."
+level: warning
+match: $title
+style: Chicago
+scope: heading
diff --git a/.vale/styles/NetwrixKB/ImpersonalFiller.yml b/.vale/styles/NetwrixKB/ImpersonalFiller.yml
new file mode 100644
index 0000000000..eafba7ad9a
--- /dev/null
+++ b/.vale/styles/NetwrixKB/ImpersonalFiller.yml
@@ -0,0 +1,18 @@
+extends: existence
+message: "Remove '%s' and state the point directly."
+level: warning
+ignorecase: true
+nonword: true
+tokens:
+  - '\bit should be noted that\b'
+  - '\bit is important to note that\b'
+  - '\bit is important to ensure that\b'
+  - '\bit is important to\b'
+  - '\bit is recommended that\b'
+  - '\bit is necessary to\b'
+  - '\bit is possible to\b'
+  - '\bit is worth noting that\b'
+  - '\bit must be noted that\b'
+  - '\bas mentioned previously\b'
+  - '\bas previously mentioned\b'
+  - '\bneedless to say\b'
diff --git a/.vale/styles/NetwrixKB/NoteThat.yml b/.vale/styles/NetwrixKB/NoteThat.yml
new file mode 100644
index 0000000000..9c4a5b55bb
--- /dev/null
+++ b/.vale/styles/NetwrixKB/NoteThat.yml
@@ -0,0 +1,7 @@
+extends: existence
+message: "Avoid '%s'. Use a blockquote callout instead: '> **NOTE:** ...' or '> **IMPORTANT:** ...'"
+level: warning
+ignorecase: true
+tokens:
+  - '\bnote that\b'
+  - '\bplease note\b'
diff --git a/.vale/styles/NetwrixKB/Please.yml b/.vale/styles/NetwrixKB/Please.yml
new file mode 100644
index 0000000000..b9b3da3601
--- /dev/null
+++ b/.vale/styles/NetwrixKB/Please.yml
@@ -0,0 +1,7 @@
+extends: existence
+message: "Avoid 'please' in instructions. Be direct."
+level: warning
+ignorecase: true
+nonword: true
+tokens:
+  - '\bplease(?!\s+note)\b'
diff --git a/.vale/styles/NetwrixKB/Utilize.yml b/.vale/styles/NetwrixKB/Utilize.yml
new file mode 100644
index 0000000000..e50ee9715e
--- /dev/null
+++ b/.vale/styles/NetwrixKB/Utilize.yml
@@ -0,0 +1,13 @@
+extends: substitution
+message: "Use '%s' — avoid 'utilize' and its variants."
+level: warning
+ignorecase: true
+swap:
+  '\butilizes\b': 'uses'
+  '\butilized\b': 'used'
+  '\butilizing\b': 'using'
+  '\butilize\b': 'use'
+  '\butilises\b': 'uses'
+  '\butilised\b': 'used'
+  '\butilising\b': 'using'
+  '\butilise\b': 'use'
diff --git a/.vale/styles/NetwrixKB/WeakLinkText.yml b/.vale/styles/NetwrixKB/WeakLinkText.yml
new file mode 100644
index 0000000000..517ad881e7
--- /dev/null
+++ b/.vale/styles/NetwrixKB/WeakLinkText.yml
@@ -0,0 +1,10 @@
+extends: existence
+message: "Avoid generic link text '%s'. Write descriptive link text that describes the destination or action."
+level: warning
+ignorecase: true
+tokens:
+  - '\bclick here\b'
+  - '\bthis link\b'
+  - '\blearn more\b'
+  - '\bsee more\b'
+  - '\bread more\b'