Merge pull request #513 from netwrix/dev

vale linter prepush, updated skills

Author: jth-nw

.claude/skills/dale/rules/negative-assumptions.yml

@@ -1,3 +1,3 @@
-message: "Do not use negative assumptions about what users can or cannot do."
+message: "Don't make negative assumptions about what users can or cannot do."
 level: warning
 reason: "This rule should trigger when the user or agent writes something that assumes a user cannot do something without the product."

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

@@ -1,6 +1,6 @@
 ---
 name: doc-pr-fix
-description: "Autonomous fixer for documentation PRs. Triggered by @claude comments on PRs targeting dev. Reads the writer's request and the existing doc-pr review, then applies fixes, runs Vale and Dale until clean, and commits. Use this skill whenever a writer tags @claude on a documentation PR — not for interactive help (use doc-help for that), but for autonomous, single-shot fixes in CI."
+description: "Autonomous fixer for documentation PRs. Triggered by @claude comments on PRs targeting dev. Reads the writer's request, the doc-pr review comment, and the Vale linting comment, then applies fixes and commits. Use this skill whenever a writer tags @claude on a documentation PR — not for interactive help (use doc-help for that), but for autonomous, single-shot fixes in CI."
 argument-hint: "[pr-number] [writer-comment]"
 ---
 
@@ -20,8 +20,9 @@ You receive:
 
 Parse the writer's comment to determine what they want. Common patterns:
 
-- **Fix all issues** — apply every fix from the doc-pr review comment
-- **Fix only Vale/Dale issues** — apply only linting fixes
+- **Fix all issues** — apply every fix from the doc-pr review comment and the Vale linting comment
+- **Fix only Vale issues** — apply only fixes from the Vale linting comment
+- **Fix only Dale issues** — apply only Dale linting fixes
 - **Fix a specific issue** — apply one targeted fix
 - **Improve flow/clarity/structure** — editorial rewrite of specific content
 - **Explain something** — answer a question about a flagged issue (respond in a PR comment, don't edit files)
@@ -35,14 +36,21 @@ Parse the writer's comment to determine what they want. Common patterns:
    ```bash
    gh api repos/{owner}/{repo}/issues/$PR_NUMBER/comments --jq '.[] | select(.body | contains("Documentation PR Review")) | .body' | tail -1
    ```
-   This tells you what Vale, Dale, and the editorial review already flagged.
+   This tells you what Dale and the editorial review flagged.
+4. If the writer asks to fix Vale issues (or "all issues"), also find the Vale linting comment:
+   ```bash
+   gh api repos/{owner}/{repo}/issues/$PR_NUMBER/comments --jq '.[] | select(.user.login == "github-actions[bot]" and (.body | contains("## Vale Linting"))) | .body' | tail -1
+   ```
+   This gives you the Vale results table with file paths, line numbers, and rule violations.
 
 ## Step 3: Apply fixes
 
 Work through the requested fixes methodically:
 
-- For **linting fixes** (Vale/Dale): fix each flagged issue in order, file by file
-- For **editorial fixes**: apply the suggested changes from the review, or if the writer asked for something broader ("improve the flow"), read the full document and apply edits that address the request while following Netwrix style
+- For **Vale fixes**: read `docs/CLAUDE.md` for Vale guidance (especially the two rules requiring extra care), then fix each flagged issue in order, file by file
+- For **Dale fixes**: fix each flagged issue in order, file by file
+- For **editorial fixes from the review**: apply the suggested changes from the review comment
+- For **broader editorial requests** ("improve the flow", "make this clearer", "help with structure"): invoke `/doc-help` with the file path and the writer's request. Doc-help will analyze the document using its structured editing framework (structure, clarity, voice, surface). Since this is running in CI without an interactive writer, apply all of doc-help's suggestions autonomously rather than waiting for feedback
 - For **explanations**: post a PR comment explaining the issue and how to fix it, then stop — don't edit files
 
 When editing:
@@ -52,15 +60,7 @@ When editing:
 
 ## Step 4: Verify
 
-After all edits, run Vale on every file you changed:
-
-```bash
-vale <file>
-```
-
-Fix any new Vale errors. Re-run until zero errors remain.
-
-Do NOT run Dale or any other skills during verification — just Vale.
+Review your edits to ensure they don't introduce new issues. Do NOT run Dale or any other skills during verification.
 
 ## Step 5: Commit and push
 
@@ -86,15 +86,15 @@ Post a PR comment summarizing what you did:
 - `path/to/file.md`: <what was fixed>
 - `path/to/other.md`: <what was fixed>
 
-Vale and Dale checks pass on all edited files.
+Dale checks pass on all edited files.
 ```
 
 If you were asked to explain something rather than fix it, your comment IS the deliverable — no summary needed.
 
 ## Behavioral Notes
 
 - **Fix what's clear, ask about what isn't.** If a request has both obvious parts and ambiguous parts, apply the obvious fixes, commit and push those, then post a comment that summarizes what you did AND asks clarifying questions about the rest. The writer can reply with another `@claude` comment to continue.
-- **Never fix issues the writer didn't ask about.** If they said "fix the Vale issues," don't also rewrite sentences for clarity.
+- **Never fix issues the writer didn't ask about.** If they said "fix the Dale issues," don't also rewrite sentences for clarity.
 - **If a fix would substantially change the author's meaning**, skip it and explain why in your summary comment. Ask the writer how they'd like to handle it.
 - **If the entire request is unclear**, don't edit anything — post a comment asking for clarification. It's better to ask one good question than to guess wrong and push unwanted changes.
 - **Each `@claude` comment is a fresh invocation.** You won't remember previous runs, so always re-read the PR diff and review comment for context.

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

@@ -1,12 +1,14 @@
 ---
 name: doc-pr
-description: "Orchestrate a full documentation review for pull requests targeting dev. Runs Vale linting, Dale linting, and editorial review on changed markdown files, then posts a structured comment to the PR. Use this skill whenever a PR involves markdown files in docs/ and targets the dev branch — triggered automatically by the doc-pr GitHub Actions workflow on PR open, sync, or when invoked manually via /doc-pr."
+description: "Orchestrate a documentation review for pull requests targeting dev. Runs Dale linting and editorial review on changed markdown files, then posts a structured comment to the PR. Vale linting runs separately via the vale-linter workflow (inline review comments + summary PR comment). Use this skill whenever a PR involves markdown files in docs/ and targets the dev branch — triggered automatically by the doc-pr GitHub Actions workflow on PR open, sync, or when invoked manually via /doc-pr."
 argument-hint: "[changed-files-csv] [pr-number]"
 ---
 
 # Doc PR Review
 
-You orchestrate a three-stage documentation review pipeline for pull requests. Your job is to run each stage, collect the results, and post a single comprehensive review comment to the PR.
+You orchestrate a two-stage documentation review pipeline for pull requests. Your job is to run each stage, collect the results, and post a single comprehensive review comment to the PR.
+
+Vale linting runs separately (via the vale-linter workflow) and posts inline review comments plus a summary PR comment. Do not run Vale or include Vale results in your review.
 
 Read `docs/CLAUDE.md` before starting — it contains the writing standards and Vale guidance you need for the editorial review stage.
 
@@ -24,17 +26,7 @@ If the environment variables are empty, check for positional arguments (`$1` = f
 
 Split the comma-separated file list into individual file paths for processing.
 
-## Stage 1: Vale Linting
-
-Run Vale on each changed file and capture the output.
-
-```bash
-vale --output=line <file>
-```
-
-Collect all Vale output. If Vale finds no issues for a file, note that file as clean. If Vale is not installed, report that Vale was unavailable and skip to Stage 2.
-
-## Stage 2: Dale Linting
+## Stage 1: Dale Linting
 
 For each changed file, invoke the Dale linter skill:
 
@@ -44,7 +36,7 @@ For each changed file, invoke the Dale linter skill:
 
 Dale returns a table of rule violations or a clean report. Collect all Dale output.
 
-## Stage 3: Editorial Review
+## Stage 2: Editorial Review
 
 This stage applies the doc-help editing analysis to the PR changes — but non-interactively. You are producing a written review, not having a conversation.
 
@@ -70,7 +62,7 @@ Only report issues on lines that were added or modified in this PR. Do not flag
 
 ## Output — MANDATORY: Post as PR Comment
 
-After completing all three 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.
+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.
 
 **Step 1: Write the review to a temporary file.**
 
@@ -79,16 +71,6 @@ Write the full review body to `/tmp/doc-pr-review.md` using the Write tool. Foll
 ```markdown
 ## Documentation PR Review
 
-### Vale Linting
-
-**path/to/file.md**
-
-| Line | Rule | Message | Offending Text |
-|------|------|---------|----------------|
-| N | `RuleName` | description of the issue | `offending text` |
-
-(Repeat for each file. Write "No issues found." if clean.)
-
 ### Dale Linting
 
 **path/to/file.md**
@@ -111,7 +93,7 @@ Write the full review body to `/tmp/doc-pr-review.md` using the Write tool. Foll
 
 ### Summary
 
-N Vale issues, N Dale issues, N editorial suggestions across N files.
+N Dale issues, N editorial suggestions across N files. Vale issues are posted in a separate comment by the vale-linter workflow.
 
 ---
 
@@ -120,7 +102,7 @@ N Vale issues, N Dale issues, N editorial suggestions across N files.
 Comment `@claude` on this PR followed by your instructions to get help:
 
 - `@claude fix all issues` — fix all Vale, Dale, and editorial issues
-- `@claude fix only the Vale issues` — fix just the linting problems
+- `@claude fix only the Vale issues` — fix just the Vale issues
 - `@claude help improve the flow of this document` — get writing assistance
 - `@claude explain the voice issues` — understand why something was flagged
 
@@ -140,6 +122,6 @@ If the `gh pr comment` command fails, report the error. Do NOT end your turn wit
 ## Behavioral Notes
 
 - Be thorough but not pedantic — focus on issues that genuinely affect reader comprehension or violate Netwrix standards
-- When Vale and your editorial review flag the same issue, include it only in the Vale section (Vale is more specific)
-- If a file has zero issues across all three stages, still list it with "No issues found." so the reviewer knows it was checked
+- Do not flag issues that Vale or Dale already catch — focus on what linters miss
+- If a file has zero issues across both stages, still list it with "No issues found." so the reviewer knows it was checked
 - Never modify the files — this is a read-only review