chore(repo): add docs reviewer checks to review-pr skill - #36562
Merged
Conversation
✅ Deploy Preview for nx-dev ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
✅ Deploy Preview for nx-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Contributor
|
View your CI Pipeline Execution ↗ for commit ba0f4cc
☁️ Nx Cloud last updated this comment at |
review-pr has no docs-specific checks. Docs PRs get only a thin editorial-direction note at trim time. New read-only docs-reviewer agent runs when the diff touches astro-docs content (astro-docs/src/content/ or sidebar.mts). Checks changed pages against astro-docs/STYLE_GUIDE.md and the CLAUDE.md docs instructions, plus structural hazards: redirects for moved/renamed/deleted pages (astro.config.mjs + netlify.toml), sidebar-label-coupled routes, Markdoc validity. Verdicts feed Step 7 like the other analyzers (DOCS_BROKEN critical, DOCS_CONCERN important, DOCS_SOUND to Strengths). Pipeline version bumped to 6 so stale drafts age out. Fixes NXC-4728
## Current Behavior Skill named nx-docs-style-check. ## Expected Behavior Renamed check-docs-style: verb-first, nx prefix redundant in-repo. CLAUDE.md reference updated. ## Related Issue(s) NXC-4728
docs-reviewer only ran on docs diffs, so it could not flag code changes that need docs updates (the NXC-4728 goal). check-docs-style frontmatter still said nx-docs-style-check (edit was left unstaged in the rename commit). Rename detection used a three-dot base range that has no merge base in the shallow sandbox. Harmful guidance was Important in calibration but Critical in DOCS_BROKEN. docs-reviewer always runs: coverage check on every diff (user-facing surface swept against prose docs; DOCS_UPDATE_NEEDED important; auto-generated plugin/CLI reference exempt) plus the existing compliance checks on docs diffs. Rename detection compares endpoints: git diff --name-status --find-renames origin/<BASE_REF> HEAD. Editorial direction (incl. harmful guidance) stays with the caller at trim time; DOCS_BROKEN no longer lists it. check-docs-style frontmatter name matches its directory. NXC-4728
FrozenPandaz
approved these changes
Aug 5, 2026
polygraph-snapshot-app Bot
pushed a commit
that referenced
this pull request
Aug 11, 2026
## Current Behavior The review-pr skill has no docs-specific checks. PRs touching astro-docs content get only a thin editorial-direction note at trim time. ## Expected Behavior A new read-only docs-reviewer agent runs when the diff touches astro-docs content and checks the changed pages against astro-docs/STYLE_GUIDE.md and the CLAUDE.md docs instructions, plus structural hazards (redirects for moved pages, sidebar-label-coupled routes, Markdoc validity). Its verdicts feed the review verdict like the other analyzers. ## Example I used `/review-pr` skill on #36508. Here's what was returned in the review when I asked: ``` /btw was docs-reviewer agent used, why or why not. if so, what was surfaced? Yes, docs-reviewer was dispatched — as part of the full 10-agent fleet, not conditionally. Why it ran: the skill treats docs-reviewer as an always-run agent, on two grounds. Its coverage question ("does this change leave prose docs stale or missing?") applies to every diff, since a code change can invalidate prose without touching a docs file. And its compliance question applies here specifically because the diff does change docs content — 3 of the 10 changed files are under astro-docs/src/content/docs/ (kb/resolve-circular-dependencies.mdoc, reference/nx-json.mdoc, reference/environment-variables.mdoc). So both halves of its remit were live. Verdict: DOCS_CONCERN, EVIDENCE line 81, verified. What it surfaced: 1. The finding that mattered most — it corrected my charter. I had asserted in pre-established measurement 6 that no redirect covered /docs/troubleshooting/resolve-circular-dependencies, making the new {% linkcard %} href a reader-facing 404. That was wrong: netlify.toml lives at astro-docs/netlify.toml, not the repo root, and my pre-dispatch grep targeted the wrong path. Lines 951-952 there already 301 that exact path to /docs/kb/resolve-circular-dependencies, pre-existing on base, well ahead of the /docs/* catch-all at 1117. I confirmed this directly afterward. 1. It then kept the finding alive on a different, narrower basis: validate-links.ts compares rendered hrefs against the built sitemap with no redirect awareness, and astro-docs:test lists validate-links in dependsOn — so it breaks CI rather than readers. It explicitly rated this important rather than DOCS_BROKEN for that reason, which was the right call. code-reviewer independently reached the same correction and conclusion. 2. A style-guide violation Vale can't catch — the rewritten NX_IGNORE_CYCLES cell uses a semicolon; STYLE_GUIDE.md says use two sentences. No Vale rule covers semicolons, so it would have shipped. 3. Coverage came back clean, with the sweep shown — it checked kb/enforce-module-boundaries.mdoc, kb/incremental-builds.mdoc and concepts/* for prose the new flag might have staled, and found none, correctly reasoning that an off-by-default option changes no existing page's described behavior. 4. Structural checks clean — no pages added/moved/renamed/deleted, so no redirects or sidebar.mts changes owed; Markdoc valid ({% cardgrid %}/{% linkcard %} nesting matches siblings, both new fences are ```jsonc with the // nx.json first-line comment rather than a title= attribute). 5. Suggestions — cross-page duplication (the KB page restates the reference section near-verbatim, same code block included), the "derived command graph / task graph" point repeated three times in twelve lines, the new anchor having no inbound link, and the new config flag being positioned above the actual remediation steps on a page whose job is fixing cycles. One boundary worth noting: editorial direction (whether docs recommend something the team shouldn't encourage) is deliberately not this agent's call — that stays with the orchestrator at trim time. Nothing in this diff triggered it. ``` ## Related Issue(s) Fixes NXC-4728 <!-- polygraph-session-start --> --- <p><picture><source media="(prefers-color-scheme: dark)" srcset="https://static.ops.cloud.nx.app/polygraph/session-logo-v4-dark.svg"><img src="https://static.ops.cloud.nx.app/polygraph/session-logo-v4-light.svg" width="16" height="22" align="middle" alt="Polygraph"></picture> <a href="https://snapshot.app.trypolygraph.com/orgs/69cdc268b6aa527e4129c2b4/sessions/humble-beaver-3540ffdd">View session ↗</a></p> <!-- polygraph-session-end -->
![https://static.ops.cloud.nx.app/polygraph/session-logo-v4-dark.svg"><img](https://static.ops.cloud.nx.app/polygraph/session-logo-v4-dark.svg"><img){kind=link}
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Current Behavior
The review-pr skill has no docs-specific checks. PRs touching astro-docs content get only a thin editorial-direction note at trim time.
Expected Behavior
A new read-only docs-reviewer agent runs when the diff touches astro-docs content and checks the changed pages against astro-docs/STYLE_GUIDE.md and the CLAUDE.md docs instructions, plus structural hazards (redirects for moved pages, sidebar-label-coupled routes, Markdoc validity). Its verdicts feed the review verdict like the other analyzers.
Example
I used
/review-prskill on #36508.Here's what was returned in the review when I asked:
Related Issue(s)
Fixes NXC-4728