Tighten docs-review skill severity to reduce review churn

[danbarr]

Description

Raises the bar for what the docs-review skill flags, reducing nit-picking and making reviews more stable across runs.

Changes:

• Add "independent reviewer test" - before including a finding, check whether a different tech writer would independently flag it
• Tighten secondary issues from "minor wording improvements" to "genuinely confusing, ambiguous, or misleading"
• Expand "Skip entirely" to explicitly exclude style-neutral alternatives, thin-but-useful sections, and cosmetic rewording
• Remove "Inline Suggestions" from the output format (magnet for style quibbles)
• Add grammatical errors to primary issues (these are objective, not subjective)

Type of change

• Other / internal

Submitter checklist

Content and formatting

• I have reviewed the content for technical accuracy
• I have reviewed the content for spelling, grammar, and style

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs-website	Ready	Preview, Comment	Apr 8, 2026 7:51pm

[Copilot]

Pull request overview

This PR updates the .claude/skills/docs-review guidance to reduce subjective/nitpicky findings and improve review stability across runs, while explicitly treating grammatical errors as objective, high-severity issues.

Changes:

• Removes the “Inline Suggestions” output section to discourage style-quibble line edits.
• Introduces an “independent reviewer test” to gate findings and avoid style-neutral rephrases.
• Tightens severity definitions: narrows “Secondary issues” to genuinely confusing/misleading content and expands explicit “Skip entirely” cases.