From 703e6da297bb38958f41bc787990ece47fdc379f Mon Sep 17 00:00:00 2001 From: Cam Date: Tue, 21 Oct 2025 00:33:00 +0000 Subject: [PATCH 1/4] Clarify review instructions in Claude Code Review workflow for line number references and suggestion formatting --- .github/workflows/claude-code-review.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/claude-code-review.yml b/.github/workflows/claude-code-review.yml index cb743813fcf7..46035187e422 100644 --- a/.github/workflows/claude-code-review.yml +++ b/.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 From 328eea0ef69d0480b940f6767106166e38bee175 Mon Sep 17 00:00:00 2001 From: Cam Date: Tue, 21 Oct 2025 22:04:14 +0000 Subject: [PATCH 2/4] Enhance documentation review instructions for clarity and detail, including PR handling and expanded review criteria --- .claude/commands/docs-review.md | 44 ++++++++++++++++++++++++++++----- 1 file changed, 38 insertions(+), 6 deletions(-) diff --git a/.claude/commands/docs-review.md b/.claude/commands/docs-review.md index e783d29336f7..5b179f412607 100644 --- a/.claude/commands/docs-review.md +++ b/.claude/commands/docs-review.md @@ -3,30 +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` to compare current branch against master +- If on master with uncommitted changes, review those changes +- 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. +- **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. From 7da6b7f0d1c109f861269df70392eb856f51f79c Mon Sep 17 00:00:00 2001 From: Cam Date: Tue, 21 Oct 2025 22:05:45 +0000 Subject: [PATCH 3/4] Improve clarity in documentation review guidelines by adjusting phrasing for technical writer and blogger roles --- .claude/commands/docs-review.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.claude/commands/docs-review.md b/.claude/commands/docs-review.md index 5b179f412607..3c8ca814b5fa 100644 --- a/.claude/commands/docs-review.md +++ b/.claude/commands/docs-review.md @@ -59,7 +59,7 @@ Always provide relevant line numbers for any issues you identify. - **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: +- When reviewing **Documentation**, serve the role of a professional technical writer. Review for: - Clarity and conciseness. - Logical flow and structure. - No jargon unless defined. @@ -69,7 +69,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. From 5cd5c072762dc8d315f3c51d84bfd8b229598fbb Mon Sep 17 00:00:00 2001 From: Cam Date: Tue, 21 Oct 2025 22:14:15 +0000 Subject: [PATCH 4/4] Clarify instructions for comparing branches in documentation review process --- .claude/commands/docs-review.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.claude/commands/docs-review.md b/.claude/commands/docs-review.md index 3c8ca814b5fa..b29926195fbf 100644 --- a/.claude/commands/docs-review.md +++ b/.claude/commands/docs-review.md @@ -17,8 +17,7 @@ You will review documentation changes and provide feedback on style, accuracy, a **If no PR number is provided**: - Use `git status` to check for uncommitted changes -- Use `git diff master` to compare current branch against master -- If on master with uncommitted changes, review those changes +- Use `git diff master...HEAD` to compare current branch against master - Review the changes according to the criteria below ## Review Criteria