Merge pull request #539 from netwrix/dev

idioms and heading punctuation

Author: jth-nw

.claude/skills/doc-pr-fix/SKILL.md

@@ -95,6 +95,19 @@ When editing:
 - Preserve the author's meaning and intent — fix the style, don't rewrite the content
 - Only change what was requested; don't fix other categories of issues even if they're on the same line (e.g., if asked to fix Vale issues, don't also fix Dale or editorial issues)
 
+## Step 4b: Update the Vale Idioms rule
+
+After applying fixes, check whether any Dale `idioms` violations or editorial items tagged `[idiom]` contained phrases not already in `.vale/styles/Netwrix/Idioms.yml`. For each new idiom:
+
+1. Read `.vale/styles/Netwrix/Idioms.yml` to confirm the phrase isn't already covered (check for both exact matches and regex patterns that would match it).
+2. Add a new token entry under the most appropriate category comment. Follow existing conventions:
+   - Use `\b` word boundaries for multi-word phrases.
+   - Add optional inflection suffixes where the idiom can be conjugated (e.g., `\bgets? the ball rolling\b`).
+   - Use single quotes around each token.
+3. Include the Idioms.yml file in your commit so the Vale rule grows over time.
+
+If no new idioms were found, skip this step.
+
 ## Step 5: Verify
 
 Review your edits to ensure they don't introduce new issues. Do NOT run Dale or any other skills during verification.

.claude/skills/doc-pr/SKILL.md

@@ -60,6 +60,10 @@ For each issue found, note:
 
 Only report issues on lines that were added or modified in this PR. Do not flag preexisting issues.
 
+**Idiom tagging:** When the editorial review catches an idiom or figurative expression, tag it with `[idiom]` at the start of the bullet so the fixer can identify it and add it to the Vale `Idioms.yml` rule. Example:
+
+- **Surface** — [idiom] Line 42: "get the ball rolling" is an idiom. Suggested fix: "begin the process"
+
 ## Output — MANDATORY: Post as PR Comment
 
 After completing both stages, you MUST write the review to a file and post it as a PR comment. This is the most important step — the review is useless if it is not posted.

.vale/styles/Netwrix/HeadingPunctuation.yml

@@ -1,11 +1,13 @@
 extends: existence
-message: "Don't end headings with terminal punctuation ('%s'). Remove the trailing character."
+message: "Don't use punctuation in headings ('%s'). Rewrite the heading to remove it."
 level: warning
 scope: heading
 nonword: true
 tokens:
-  - '\.$'
-  - ':$'
-  - ';$'
-  - '\?$'
-  - '!$'
+  - '\.'
+  - ':'
+  - ';'
+  - '\?'
+  - '!'
+  - '\('
+  - '\)'

.vale/styles/Netwrix/HitVsClick.yml

@@ -0,0 +1,90 @@
+extends: existence
+message: "Avoid the idiom '%s'. Write what you mean directly and literally."
+level: warning
+ignorecase: true
+tokens:
+  # Overarching / scope idioms
+  - 'tip of the iceberg'
+  - 'at the end of the day'
+  - '\bout of the box\b'
+  - '\bout-of-the-box\b'
+  - '\bin-the-box\b'
+  - '\bunder the hood\b'
+  - '\bin a nutshell\b'
+  - '\bon the same page\b'
+  - '\bfrom the ground up\b'
+  - '\bbehind the scenes\b'
+  - '\bout of the gate\b'
+  - '\boff the beaten path\b'
+  - '\bthe big picture\b'
+  - '\bthe bottom line\b'
+
+  # Status / momentum idioms
+  - '\bup and running\b'
+  - '\bhit the ground running\b'
+  - '\bramp(?:s|ed|ing)? up\b'
+  - '\bspin(?:s|ning)? up\b'
+  - '\bstand(?:s|ing)? up\b'
+  - '\btear(?:s|ing)? down\b'
+  - '\btore? down\b'
+
+  # Business/strategy jargon
+  - '\blow.hanging fruit\b'
+  - '\bmoves? the needle\b'
+  - '\bboil(?:s|ed|ing)? the ocean\b'
+  - '\blevels? the playing field\b'
+  - '\braises? the bar\b'
+  - '\bsets? the stage\b'
+  - '\bpaves? the way\b'
+  - '\bbridges? the gap\b'
+  - '\bfills? the gap\b'
+  - '\bcut(?:s|ting)? corners\b'
+  - '\brule of thumb\b'
+  - '\bacross the board\b'
+  - '\bin the long run\b'
+  - '\bin the same boat\b'
+
+  # Attention/awareness idioms
+  - '\bkeep in mind\b'
+  - '\bbear in mind\b'
+  - '\bat your fingertips\b'
+  - '\bon the radar\b'
+  - '\bin the weeds\b'
+  - '\bat first glance\b'
+  - '\bby the same token\b'
+  - '\bon the fly\b'
+
+  # Collaboration/process jargon
+  - '\btouch(?:es|ing|ed)? base\b'
+  - '\bcircle(?:s|d|ing)? back\b'
+  - '\bloop(?:s|ed|ing)? in\b'
+  - '\bflesh(?:es|ed|ing)? out\b'
+  - '\biron(?:s|ed|ing)? out\b'
+  - '\bhammer(?:s|ed|ing)? out\b'
+  - '\bdrill(?:s|ed|ing)? down\b'
+  - '\bzero(?:s|ed|ing)? in on\b'
+  - '\bhone(?:s|d|ing)? in on\b'
+
+  # Deep dive variants
+  - '\ba deep dive\b'
+  - '\bdeep dive\b'
+  - '\btake a deep dive\b'
+
+  # Work idioms
+  - '\bfrom scratch\b'
+  - '\bheavy lifting\b'
+  - '\bpain points?\b'
+
+  # Tech marketing buzzwords
+  - '\bgame.changer\b'
+  - '\bsilver bullet\b'
+  - '\bmagic bullet\b'
+  - '\bone.stop.shop\b'
+  - '\bbest of breed\b'
+  - '\bbleeding.?edge\b'
+  - '\bcutting.?edge\b'
+  - '\bmission.critical\b'
+  - '\bworld.class\b'
+  - '\bturnkey\b'
+  - '\bsynergy\b'
+  - '\bleverage(?:s|d|ing)?\b'