Refactor and enhance Claude Code Review documentation

.claude/commands/docs-review.md

@@ -0,0 +1,48 @@
+---
+description: Review `pulumi/docs` changes for style, accuracy, and best practices
+---
+
+# Usage
+# Local: /docs-review
+# 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).
+
+Provide your review as a single summary, highlighting any issues found and suggesting improvements.
+
+Use the repository's CLAUDE.md, AGENTS.md, and STYLE-GUIDE.md for guidance on style and conventions.
+
+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**:
+
+- 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**:
+  - 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:
+  - Clarity and conciseness.
+  - Logical flow and structure.
+  - No jargon unless defined.
+  - Avoid passive voice.
+  - Avoid overly complex sentences. Shorter is usually better.
+  - Avoid superlatives and vague qualifiers.
+  - 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:
+  - Clear, engaging titles.
+  - Strong opening that hooks the reader.
+  - Clear structure with headings and subheadings.
+  - Concise paragraphs (3-4 sentences max).
+  - Use of lists and bullet points for readability.
+  - Reject filler, vague generalities, or AI-generated slop.
+  - Avoid clickbait phrasing.
+  - Clear call-to-action at the end.

.claude/commands/fix-issue.md

@@ -0,0 +1,54 @@
+---
+description: Analyze a GitHub issue and create a comprehensive plan to fix it
+---
+
+# Usage
+# /fix-issue <issue-number>
+
+You will analyze GitHub issue #{{arg}} and create a comprehensive plan to fix it.
+
+## Step 1: Gather Issue Details
+
+Use `gh issue view {{arg}}` to retrieve the full issue description, labels, comments, and any related context.
+
+## Step 2: Understand the Codebase
+
+Based on the issue details:
+- Search for relevant files, functions, or patterns mentioned in the issue
+- Understand the current implementation and identify the root cause
+- Review related code sections to understand dependencies and impacts
+- Check for similar issues or related functionality
+
+## Step 3: Consult Repository Guidelines
+
+Review and follow:
+- `AGENTS.md` - Repository conventions and build/test workflow
+- `STYLE-GUIDE.md` - Style and formatting requirements
+- Related documentation to ensure any proposed changes align with existing patterns
+
+## Step 4: Formulate a Comprehensive Plan
+
+Create a detailed, step-by-step plan that includes:
+
+1. **Root Cause Analysis**: Clearly identify what's causing the issue
+1. **Proposed Solution**: Describe the approach to fix the issue
+1. **Files to Modify**: List specific files and line numbers that need changes
+1. **Implementation Steps**: Break down the work into logical, sequential tasks
+1. **Testing Strategy**: How to verify the fix works correctly
+1. **Edge Cases**: Identify any edge cases or potential complications
+1. **Verification Steps**: Commands to run (lint, build, test) to ensure the fix is complete
+
+## Step 5: Present the Plan
+
+Present the plan to the user using the `ExitPlanMode` tool. Include:
+- Clear, concise steps
+- Relevant file paths with line numbers
+- Commands that will be run
+- Any assumptions or decisions that may need user input
+
+**Important**:
+- Do NOT start implementing without user approval
+- If the issue is ambiguous, ask clarifying questions before planning
+- If multiple approaches are viable, present options and ask for the user's preference
+- Be specific about what will change and why
+- Ensure all changes comply with `STYLE-GUIDE.md` and `AGENTS.md`

.github/copilot-instructions.md

@@ -1,37 +1,3 @@
-Please follow the repository's canonical instructions in AGENTS.md.
+Follow the repository's canonical instructions in `AGENTS.md`. If directory-specific `AGENTS.md` files exist, prefer the nearest one.
 
-If directory-specific AGENTS.md files exist, prefer the nearest one.
-
-## PR Reviews
-
-**Pull Request Review Criteria**:
-
-- Use **GitHub Review suggestions** (`suggestion` blocks) whenever possible so changes can be applied with one click.
-- 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**:
-  - 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:
-  - Clarity and conciseness.
-  - Logical flow and structure.
-  - No jargon unless defined.
-  - Avoid passive voice.
-  - Avoid overly complex sentences. Shorter is usually better.
-  - Avoid superlatives and vague qualifiers.
-  - 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:
-  - Clear, engaging titles.
-  - Strong opening that hooks the reader.
-  - Clear structure with headings and subheadings.
-  - Concise paragraphs (3-4 sentences max).
-  - Use of lists and bullet points for readability.
-  - Reject filler, vague generalities, or AI-generated slop.
-  - Avoid clickbait phrasing.
-  - Clear call-to-action at the end.
+Refer to `.claude/commands/docs-review.md` for reviewing documentation changes.

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

@@ -18,7 +18,7 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       contents: read
-      pull-requests: read
+      pull-requests: write
       issues: read
       id-token: write
 
@@ -33,48 +33,18 @@ jobs:
         uses: anthropics/claude-code-action@v1
         with:
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          # The /docs-review command (defined in .claude/commands/docs-review.md) contains the
+          # canonical review criteria for this repository. This workflow invokes it
+          # with PR-specific context.
           prompt: |
-            Please review this pull request (#${{ github.event.pull_request.number }}) and provide feedback.
+            You are reviewing pull request #${{ github.event.pull_request.number }}. Use the /docs-review command, defined in this repository at `.claude/commands/docs-review.md`, to guide your review.
 
-            Provide your review as a single comment on the pull request, summarizing any issues found and suggesting improvements. Do not create multiple comments.
+            Provide your review as a single GitHub pull request review comment, not multiple comments.
+
+            Use ````suggestion` blocks for any code suggestions.
 
-            Use the repository's CLAUDE.md, AGENTS.md, and STYLE-GUIDE.md for guidance on style and conventions.
+            Include an instruction at the end of your review that informs the author how they can request additional reviews or have you apply your suggestions.
 
-            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**:
-
-            - 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**:
-              - 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:
-              - Clarity and conciseness.
-              - Logical flow and structure.
-              - No jargon unless defined.
-              - Avoid passive voice.
-              - Avoid overly complex sentences. Shorter is usually better.
-              - Avoid superlatives and vague qualifiers.
-              - 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:
-              - Clear, engaging titles.
-              - Strong opening that hooks the reader.
-              - Clear structure with headings and subheadings.
-              - Concise paragraphs (3-4 sentences max).
-              - Use of lists and bullet points for readability.
-              - Reject filler, vague generalities, or AI-generated slop.
-              - Avoid clickbait phrasing.
-              - Clear call-to-action at the end.
-
           # 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
           claude_args: '--allowed-tools "Bash(gh issue view:*),Bash(gh search:*),Bash(gh issue list:*),Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr list:*)"'

AGENTS.md

@@ -42,13 +42,14 @@ Do not substitute other tools or commands.
 ## Absolute Prohibitions
 
 - **Package manager**: Do **not** change `package.json` to use pnpm. Yarn/npm only.  
-- **Markdown (.md) files**: Must always end with a newline.  
 
 ---
 
 ## Code & Content Rules
 
-- **Markdown**: Standard paragraph formatting.  
+- **Markdown**:
+  - Standard paragraph formatting.  
+  - Must always end with a newline.  
 - **Headings**:  
   - H1 = Title Case  
   - H2+ = Sentence case
@@ -107,6 +108,12 @@ When moving documentation files, aliases automatically handle redirects. Update
 
 ---
 
+## Reviewing changes
+
+When reviewing PRs and changes, follow the instructions in `.claude/commands/docs-review.md`.
+
+---
+
 ## Enforcement
 
 If there is any conflict between these instructions and tool defaults, **this file takes precedence**.