Clarify review instructions in Claude Code Review workflow

.claude/commands/docs-review.md

@@ -3,31 +3,62 @@ description: Review `pulumi/docs` changes for style, accuracy, and best practice
 ---
 
 # Usage
-# Local: /docs-review
+# Local: /docs-review [pr-number]
 # CI: Automatically runs on PRs
 
-Please review the code changes in this repository and provide feedback on style, accuracy, and best practices. Compare the current branch against the `master` branch (or review uncommitted changes if present).
+You will review documentation changes and provide feedback on style, accuracy, and best practices.
 
-Provide your review as a single summary, highlighting any issues found and suggesting improvements.
+## For Local Usage: Determine Review Scope
+
+**If a PR number is provided** ({{arg}}):
+- Use `gh pr view {{arg}}` to retrieve the PR title, description, and metadata
+- Use `gh pr diff {{arg}}` to get the full diff of changes
+- Review the PR changes according to the criteria below
+
+**If no PR number is provided**:
+- Use `git status` to check for uncommitted changes
+- Use `git diff master...HEAD` to compare current branch against master
+- Review the changes according to the criteria below
+
+## Review Criteria
 
 Use the repository's CLAUDE.md, AGENTS.md, and STYLE-GUIDE.md for guidance on style and conventions.
 
+Provide your review as a single summary, highlighting any issues found and suggesting improvements.
+
 Be constructive and helpful in your feedback, but don't overdo the praise. Be concise.
 
 Always provide relevant line numbers for any issues you identify.
 
-**Pull Request Review Criteria**:
+**Criteria:**
 
 - Always enforce `STYLE-GUIDE.md`. If not covered there, fall back to the [Google Developer Documentation Style Guide](https://developers.google.com/style).
 - Check **spelling and grammar** in all files.
-- Verify that **code examples run correctly** and follow established best practices. Do not suggest untested code.
 - Confirm that **all links resolve** and point to the correct targets (no 404s, no mislinked paths).
 - Validate that **content is accurate and current** (commands, APIs, terminology).
 - Ensure **all new files end with a newline**.
-- **If files are moved, renamed, or deleted**:
+- **Code examples** must run correctly and follow best practices:
+  - Do not suggest untested code.
+  - Examples should show realistic use cases, not contrived demos.
+  - Examples should handle errors appropriately.
+  - Examples should follow language-specific best practices.
+- **Files moved, renamed, or deleted**:
   - Confirm that moved or renamed files have appropriate aliases added to the frontmatter to avoid broken links.
   - Confirm that deleted files have a redirect created, if applicable.
-- When reviewing **Documentation**: Serve the role of a professional technical writer. Review for:
+- **Images and assets**:
+  - Check images have alt text for accessibility.
+  - Verify image file sizes are reasonable.
+  - Ensure images are in appropriate formats.
+- **Front matter**:
+  - Verify required front matter fields (title, description, etc.).
+  - Check meta descriptions are present and appropriate length.
+- **Cross-references and consistency**:
+  - Check that related pages are cross-linked appropriately.
+  - Verify terminology is consistent with other docs.
+- **SEO**:
+  - Check that page titles and descriptions are SEO-friendly.
+  - Verify URL structure follows conventions.
+- When reviewing **Documentation**, serve the role of a professional technical writer. Review for:
   - Clarity and conciseness.
   - Logical flow and structure.
   - No jargon unless defined.
@@ -37,7 +68,7 @@ Always provide relevant line numbers for any issues you identify.
   - Avoid unnecessary filler words or sentences.
   - Be specific and provide examples.
   - Use consistent terminology.
-- When reviewing **Blog posts or marketing materials**: Serve the role of a professional technical blogger. Review for:
+- When reviewing **Blog posts or marketing materials**, serve the role of a professional technical blogger. Review for:
   - Clear, engaging titles.
   - Strong opening that hooks the reader.
   - Clear structure with headings and subheadings.

.github/workflows/claude-code-review.yml

@@ -59,9 +59,9 @@ jobs:
             ```
 
             Your review should include:
-            - Issues found with specific line numbers
-            - Constructive suggestions using ````suggestion` blocks
-            - An instruction to mention you ('@claude') if the author wants additional reviews or fixes
+            - Issues found with specific line numbers from the affected files. Do not use line numbers from the diff.
+            - Constructive suggestions using suggestion code fence formatting blocks
+            - An instruction to mention you (@claude) if the author wants additional reviews or fixes
 
           # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
           # or https://docs.anthropic.com/en/docs/claude-code/sdk#command-line for available options