Pre-PR style check, doc-draft skill, and product briefs

[jth-nw]

Summary

Adds /doc-draft, a skill that writes new Netwrix documentation from source material and lints it before the PR. It replaces the tech-writer agent. The PR also adds the pre-PR style check that /doc-draft and writers share, product briefs that give the skill context, and a page-structure guide.

What /doc-draft does

Give it a PR, a work item, specs or notes, or a request to structure a new docs directory. It reads the source, drafts into the docs tree, checks coverage, lints, and reports what it did.

Source	What it reads
Pull request	The diff, then the full code in a local clone (tests included, since they show edge cases), UI strings and defaults. It searches the existing docs to decide new page, new section, or edit.
GitHub issue, Jira ticket, Azure DevOps item	The item, its comments and linked PRs, plus any Xchange articles it links. The code wins over the ticket on behavior. The ticket supplies what the code can't show. Ticket keys and customer names stay out of the page.
Specs, notes, a prompt	The text only. It marks gaps as {/* TODO */} and never invents facts.
New product or version	The documentation-section guide: required zones, order, folders, _category_.json.

Every draft:

• starts with frontmatter that includes a description
• gives each procedure an example, or a TODO when the source has none
• uses short, plain sentences without dropping any fact or qualifier
• passes a coverage check against the source (flags, defaults, limits, errors, side effects, what can't be undone) before linting
• states a caveat the code shows on the page, not only in a TODO
• has its internal links checked
• is linted with npm run quality:check (Vale, Dale, AI-isms), up to 3 rounds
• ends with a report: what it chose and why, every source read, every TODO, and any place the code disagrees with the PR, a swagger file, or an existing page

After the report it offers once to write a product brief when the product has none. It fixes docs/<product>/CLAUDE.md or the brief only where its changes made a stated fact false.

Context the skill reads

• .claude/references/products/<product>.md: briefs for auditor, dataclassification, endpointprotector, pingcastle, threatmanager and threatprevention. Each covers what the product is, where things live in the code, code-to-UI vocabulary, and what couldn't be verified.
• docs/<product>/CLAUDE.md for auditor, dataclassification, endpointprotector and threatprevention (new), and threatmanager (updated: it listed 2 of its 4 versions).
• .claude/references/page-structure-guide.md: page types, new page vs section vs edit, titles, reference pages and glossaries, API docs.
• .claude/references/lint-rules.md: a generated digest of the lint rules, so the first draft avoids them.

Pre-PR style check

Vale, Dale (a model check; 2 of 3 runs must agree) and an AI-writing check run at commit on the lines the change adds. The Stop hook runs the same check on the docs a Claude session edited, up to 3 rounds. It is skipped in CI and when dependencies aren't installed. A failed model call skips Dale and doesn't block the commit. vale-autofix.yml remains the PR-side backstop. git commit --no-verify skips the check.

How it compares

I ran /doc-draft on two Data Classification features and scored it against a code-derived fact list and the team's existing pages. These existing pages may not come from generate-issue-documentation, which I couldn't confirm.

Feature	/doc-draft	Team's pages
Graph Exchange sources (74 must-have facts)	43 covered, 1 wrong	14 covered, 4 wrong
Government cloud (41 must-have facts)	33 covered, 0 wrong	3 covered, 3 wrong

The team's pages named the Graph permissions, which the code doesn't state. That motivated the Xchange and Jira steps in the skill.

Review notes

• The briefs come from code surveys and haven't been reviewed by product owners. Each lists what it couldn't verify.
• The Jira and Xchange steps are untested. The author has no Jira access.
• .claude/ is gitignored, so the new reference files were added with git add -f.
• This PR also fixes two CodeQL alerts and the review findings on the check scripts, and adds js-yaml to devDependencies.

🤖 Generated with Claude Code

[github-actions]

Code Review

No security problems found. The new workflow uses pull_request (not pull_request_target) with contents: read, and nothing passes untrusted input to a shell (claude -p gets its arguments through spawn, and page text goes in on stdin). The issues below are about behavior.

1. The pre-commit quality step blocks commits on Vale suggestions
scripts/quality/lib/vale.mjs (runVale) runs vale with the repo's .vale.ini, where MinAlertLevel = suggestion. It keeps every alert on a changed line and never looks at Severity. check.mjs then fails the page on any finding. As a result, a suggestion-level alert blocks the commit, even though the existing pre-push step only blocks on warnings and errors (blockingAlerts drops suggestions). The hk.pkl comment also says pre-commit leftovers "are reported, not blocked." Fix: filter to Severity !== 'suggestion', or match whatever scripts/vale-local.mjs treats as blocking. The step also uses .vale.ini instead of .vale-local.ini, so local hooks no longer run one consistent rule set.

2. The quality and vale pre-commit steps can run at the same time
.config/hk.pkl: quality reads the index (git show :file). The vale step in the same hook runs --fix and restages files. hk runs steps in parallel unless depends is set, so quality can read the text from before the fix. It can then block a commit on findings that the fix step clears. Add depends = List("vale") to quality.

3. The pre-commit hook crashes if dependencies are missing
check.mjs imports @anthropic-ai/sdk (via lib/llm.mjs) and js-yaml (via lib/dale.mjs) at load time. A writer who pulls this change without running npm install gets an ERR_MODULE_NOT_FOUND crash, and every commit that touches docs is blocked. The Stop hook guards against this ([ -d node_modules/js-yaml ] && ...), but the pre-commit step doesn't. Either add the same guard, or load the SDK only when a model call is actually made.

4. TokenIgnores in .vale.ini turns off part of an existing CI rule
The new (\*\*[^*\n]+\*\*) ignore hides all bold text from every rule. Netwrix/PlainTextAdmonition exists to catch **NOTE:** and **CAUTION:** (two of its four tokens). With this ignore, it can't see them anymore, so CI (vale-autofix) stops flagging the most common form of a plain-text admonition. Exclude those patterns from the ignore, or move the admonition check to scope: raw. Vale didn't run on any doc in this PR's CI (No docs markdown files changed), so CI hasn't tested the new TokenIgnores line at all. That includes the “ escapes.

5. The Stop hook keeps blocking on later turns
.claude/hooks/stop-quality-check.sh: the session's edited-file list (nwx-quality-files-<session>) is never cleared. After 3 rounds, the hook deletes the counter and lets Claude stop. On the next turn, even one unrelated to docs, the counter starts at 0 again and the same unresolved findings block for 3 more rounds. Keep the counter after the 3rd round, or clear the file list. Also, $(cat "$LIST") is unquoted, so a path containing a space is split into separate arguments to todo-check.mjs.

Minor

• script-tests.yml runs npm run test:scripts, which vale-autofix.yml already runs in its test-scripts job. PRs that touch scripts/** now run the same tests twice (both appear in this PR's checks).
• lib/consensus.mjs verifyFindings gives each Dale finding the line number of the first line containing the quote. If an unchanged line earlier in the page has the same text, the finding gets that line number, and the inRanges filter drops it without any message.

[Denis-A-Netwrix]

It's awkward that this PR is merged without approvals