diff --git a/.claude/skills/doc-pr-fix/SKILL.md b/.claude/skills/doc-pr-fix/SKILL.md index 8b10f9578f..7d17aae408 100644 --- a/.claude/skills/doc-pr-fix/SKILL.md +++ b/.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. diff --git a/.claude/skills/doc-pr/SKILL.md b/.claude/skills/doc-pr/SKILL.md index 3d99d1f0a0..f164d87a3d 100644 --- a/.claude/skills/doc-pr/SKILL.md +++ b/.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. diff --git a/.vale/styles/Netwrix/HeadingPunctuation.yml b/.vale/styles/Netwrix/HeadingPunctuation.yml index 3c54564790..0ed367dd3a 100644 --- a/.vale/styles/Netwrix/HeadingPunctuation.yml +++ b/.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: - - '\.$' - - ':$' - - ';$' - - '\?$' - - '!$' + - '\.' + - ':' + - ';' + - '\?' + - '!' + - '\(' + - '\)' diff --git a/.vale/styles/Netwrix/HitVsClick.yml b/.vale/styles/Netwrix/HitVsClick.yml deleted file mode 100644 index cef6c05f69..0000000000 --- a/.vale/styles/Netwrix/HitVsClick.yml +++ /dev/null @@ -1,6 +0,0 @@ -extends: substitution -message: "Use 'click' instead of 'hit' for UI elements. Don't use 'click on' — just 'click'." -level: warning -ignorecase: true -swap: - '\bhit\b': 'click' diff --git a/.vale/styles/Netwrix/Idioms.yml b/.vale/styles/Netwrix/Idioms.yml new file mode 100644 index 0000000000..9b39436deb --- /dev/null +++ b/.vale/styles/Netwrix/Idioms.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'