doc pr workflow, skill updates

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

@@ -34,19 +34,17 @@ This stage applies the doc-help editing analysis to the PR changes — but non-i
 
 1. Run `gh pr diff $DOC_PR_NUMBER` to get the diff
 2. For each changed file, read the full file content
-3. Analyze ONLY the added or modified lines (lines starting with `+` in the diff) against these four priorities:
+3. Analyze ONLY the added or modified lines (lines starting with `+` in the diff) against these priorities:
 
-   **Structure** — Is the order logical? Does the overview set up what follows? Are heading levels correct?
+   **Structure** — Is the document organized so readers can find what they need? Can a reader scanning the page quickly find the section they need? For procedures, can someone follow it step by step? For explanatory content, does it build from simple to complex?
 
-   **Clarity** — Are there sentences that are hard to parse? Concepts introduced without examples? Ambiguous references?
+   **Clarity** — Is the content easy to understand? Can the reader follow the explanation without having to reread, guess at meaning, or fill in gaps?
 
-   **Voice** — Passive constructions, first person, impersonal phrases, condescending language? Does it follow Netwrix style (active voice, present tense, second person for procedures)?
-
-   **Surface** — Word choice, wordiness, redundancy? Anything the auto-fix linters might miss?
+   **Completeness** — After reading, can the reader do what they came to do? Are there gaps that would force them to search elsewhere or open a support ticket?
 
 For each issue found, note:
 - The file path and line number
-- The priority category (Structure, Clarity, Voice, or Surface)
+- The priority category (Structure, Clarity, or Completeness)
 - A specific description of the problem
 - A concrete suggested fix
 
@@ -62,7 +60,7 @@ After completing the review, you MUST write the results to a file and post it as
 
 **Step 1: Write the review to a temporary file.**
 
-Write the full review body to `/tmp/doc-pr-review.md` using the Write tool. Follow this structure:
+Write the full review body to `/tmp/doc-pr-review.md` using the Write tool. Follow this structure exactly — the footer with `@claude` instructions MUST be included in every review:
 
 ```markdown
 ## Documentation PR Review
@@ -73,7 +71,7 @@ Write the full review body to `/tmp/doc-pr-review.md` using the Write tool. Foll
 
 - **Structure** — Line N: description. Suggested fix: "..."
 - **Clarity** — Line N: description. Suggested fix: "..."
-- **Voice** — Line N: description. Suggested fix: "..."
+- **Completeness** — Line N: description. Suggested fix: "..."
 
 (Repeat for each file. Write "No issues found." if clean.)
 

.github/workflows/claude-doc-pr.yml

@@ -81,58 +81,18 @@ jobs:
         uses: anthropics/claude-code-action@v1
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          DOC_PR_FILES: ${{ steps.changed-files.outputs.files }}
+          DOC_PR_NUMBER: ${{ github.event.pull_request.number }}
+          DOC_PR_REPO: ${{ github.repository }}
         with:
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
           github_token: ${{ secrets.GITHUB_TOKEN }}
           show_full_output: true
           prompt: |
-            You are a documentation reviewer. Your ONLY job is to:
-            1. Read the PR diff and changed files
-            2. Do a brief editorial review
-            3. Post a formatted review comment to the PR
+            /doc-pr
 
-            CONTEXT:
-            - Repository: ${{ github.repository }}
-            - PR number: ${{ github.event.pull_request.number }}
-            - Changed files: ${{ steps.changed-files.outputs.files }}
-            - PR diff is at: /tmp/pr-diff.txt
-
-            NOTE: Vale and Dale issues are auto-fixed separately by the vale-autofix workflow. Do not run Vale, Dale, or include their issues in this review.
-
-            INSTRUCTIONS:
-
-            Step 1: Read /tmp/pr-diff.txt to see what changed. Then read each changed file to understand context.
-
-            Step 2: Do a brief editorial review of ONLY added/modified lines, focusing on:
-            - Voice: passive voice, first person, impersonal phrases
-            - Clarity: hard-to-parse sentences, ambiguous references
-            - Surface: wordiness, redundancy
-            Do NOT duplicate issues already caught by Vale or Dale (both auto-fixed separately) — focus on what linters miss.
-
-            Step 3: Write the review to /tmp/doc-pr-review.md with this EXACT structure:
-
-            ## Documentation PR Review
-
-            ### Editorial Review
-            (list editorial issues as bullet points: **Category** — Line N: description. Suggested fix: "...")
-            (if no issues found, write "No editorial issues found.")
-
-            ### Summary
-            N editorial suggestions across N files. Vale and Dale issues are auto-fixed separately.
-
-            ---
-            **What to do next:**
-            Comment `@claude` on this PR followed by your instructions. For example:
-            - `@claude fix all issues` — fix all editorial issues
-            - `@claude reorganize the prerequisites section`
-            - `@claude help improve the flow of this document`
-            > Automated fixes are only available for branches in this repository, not forks.
-
-            Step 4: Post the comment by running this exact command:
-            gh pr comment ${{ github.event.pull_request.number }} --repo ${{ github.repository }} --body-file /tmp/doc-pr-review.md
-
-            IMPORTANT: You MUST complete all 4 steps. Your task is NOT done until step 4 succeeds.
-          claude_args: '--allowedTools "Bash,Read,Write"'
+            The PR diff is already saved at /tmp/pr-diff.txt — read it instead of running gh pr diff.
+          claude_args: '--allowedTools "Bash,Read,Write,Glob,Grep,Skill(doc-pr)"'
 
       - name: Verify review was posted
         if: steps.changed-files.outputs.count > 0

.vale/styles/Netwrix/FormalHedging.yml

@@ -0,0 +1,12 @@
+extends: substitution
+message: "Use '%s' instead of '%s'."
+level: warning
+ignorecase: true
+swap:
+  'prior to': 'before'
+  'subsequent to': 'after'
+  'in the event that': 'if'
+  'in the event of': 'if there is'
+  'for the purpose of': 'to'
+  'with the intention of': 'to'
+  'at this point in time': 'now'

.vale/styles/Netwrix/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'

.vale/styles/Netwrix/WhetherOrNot.yml

@@ -0,0 +1,6 @@
+extends: substitution
+message: "Use '%s' instead of 'whether or not'. The 'or not' is redundant."
+level: warning
+ignorecase: true
+swap:
+  'whether or not': 'whether'