From ce9df9ddf097c1530b389367e1c077f11a810a4e Mon Sep 17 00:00:00 2001 From: Cam Date: Fri, 17 Oct 2025 18:14:25 +0000 Subject: [PATCH 1/6] Refactor documentation review guidelines and update Claude Code Review workflow permissions --- .claude/commands/docs-review.md | 48 ++++++++++++++++++++++++ .github/copilot-instructions.md | 38 +------------------ .github/workflows/claude-code-review.yml | 46 ++++------------------- 3 files changed, 57 insertions(+), 75 deletions(-) create mode 100644 .claude/commands/docs-review.md diff --git a/.claude/commands/docs-review.md b/.claude/commands/docs-review.md new file mode 100644 index 000000000000..8de942e883d1 --- /dev/null +++ b/.claude/commands/docs-review.md @@ -0,0 +1,48 @@ +--- +description: Review code 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. If there are no uncommitted changes, compare the current branch against the `master` branch. + +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. diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index e57ca0a4da6b..f118d1c8551e 100644 --- a/.github/copilot-instructions.md +++ b/.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. \ No newline at end of file +Use .claude/commands/docs-review.md for reviewing documentation changes. diff --git a/.github/workflows/claude-code-review.yml b/.github/workflows/claude-code-review.yml index c066e991efd3..e56dcae83adf 100644 --- a/.github/workflows/claude-code-review.yml +++ b/.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,16 @@ 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. + /docs-review - Provide your review as a single comment on the pull request, summarizing any issues found and suggesting improvements. Do not create multiple comments. + You are reviewing pull request #${{ github.event.pull_request.number }}. - Use the repository's CLAUDE.md, AGENTS.md, and STYLE-GUIDE.md for guidance on style and conventions. + Provide your review as a single comment on the pull request (not multiple comments). - 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:*)"' From dbdbe96bc62063fb55c143086784ffa1fc7e8fdc Mon Sep 17 00:00:00 2001 From: Cam Date: Fri, 17 Oct 2025 18:30:42 +0000 Subject: [PATCH 2/6] Enhance documentation for Claude Code Review by specifying usage instructions and improving clarity in review criteria --- .claude/commands/docs-review.md | 2 +- .github/copilot-instructions.md | 4 ++-- .github/workflows/claude-code-review.yml | 8 +++++--- 3 files changed, 8 insertions(+), 6 deletions(-) diff --git a/.claude/commands/docs-review.md b/.claude/commands/docs-review.md index 8de942e883d1..575d4e4952f7 100644 --- a/.claude/commands/docs-review.md +++ b/.claude/commands/docs-review.md @@ -1,5 +1,5 @@ --- -description: Review code changes for style, accuracy, and best practices +description: Review `pulumi/docs` changes for style, accuracy, and best practices --- # Usage diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index f118d1c8551e..41f5e92597d6 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,3 +1,3 @@ -Follow the repository's canonical instructions in AGENTS.md. If directory-specific AGENTS.md files exist, prefer the nearest one. +Follow the repository's canonical instructions in `AGENTS.md`. If directory-specific `AGENTS.md` files exist, prefer the nearest one. -Use .claude/commands/docs-review.md for reviewing documentation changes. +Use `.claude/commands/docs-review.md` for reviewing documentation changes. diff --git a/.github/workflows/claude-code-review.yml b/.github/workflows/claude-code-review.yml index e56dcae83adf..2ce08e959a63 100644 --- a/.github/workflows/claude-code-review.yml +++ b/.github/workflows/claude-code-review.yml @@ -37,11 +37,13 @@ jobs: # canonical review criteria for this repository. This workflow invokes it # with PR-specific context. prompt: | - /docs-review + 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. - You are reviewing pull request #${{ github.event.pull_request.number }}. + Provide your review as a GitHub pull request review comment with an "Approve", "Request Changes", or "Comment" decision. Use ````suggestion` blocks for any code suggestions. - Provide your review as a single comment on the pull request (not multiple comments). + Provide all your feedback as a single review comment, not multiple comments. + + Include an instruction at the end of your review that informs the author how to request a new review from you after they have addressed your feedback. # 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 a1d6b1efbdf20ac320ad7933fa02dba388e0ff98 Mon Sep 17 00:00:00 2001 From: "claude[bot]" <41898282+claude[bot]@users.noreply.github.com> Date: Fri, 17 Oct 2025 18:44:18 +0000 Subject: [PATCH 3/6] Add missing trailing newlines and improve clarity - Add missing newlines to .github/copilot-instructions.md and .claude/commands/docs-review.md per AGENTS.md requirement - Clarify usage instruction in docs-review.md to be consistent for both local and CI usage Co-authored-by: Cam Soper --- .claude/commands/docs-review.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.claude/commands/docs-review.md b/.claude/commands/docs-review.md index 575d4e4952f7..e783d29336f7 100644 --- a/.claude/commands/docs-review.md +++ b/.claude/commands/docs-review.md @@ -6,7 +6,7 @@ description: Review `pulumi/docs` changes for style, accuracy, and best practice # 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. If there are no uncommitted changes, compare the current branch against the `master` branch. +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. From 5bced66a89bbb9790b687fe4f9c0a4ee411fb5f1 Mon Sep 17 00:00:00 2001 From: Cam Date: Fri, 17 Oct 2025 18:59:14 +0000 Subject: [PATCH 4/6] Update Claude Code Review instructions for single comment feedback and clarify review request process --- .claude/commands/fix-issue.md | 54 ++++++++++++++++++++++++ .github/workflows/claude-code-review.yml | 8 ++-- 2 files changed, 58 insertions(+), 4 deletions(-) create mode 100644 .claude/commands/fix-issue.md diff --git a/.claude/commands/fix-issue.md b/.claude/commands/fix-issue.md new file mode 100644 index 000000000000..aada3997c1ce --- /dev/null +++ b/.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 + +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` diff --git a/.github/workflows/claude-code-review.yml b/.github/workflows/claude-code-review.yml index 2ce08e959a63..0e6ce34b273e 100644 --- a/.github/workflows/claude-code-review.yml +++ b/.github/workflows/claude-code-review.yml @@ -39,11 +39,11 @@ jobs: prompt: | 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 GitHub pull request review comment with an "Approve", "Request Changes", or "Comment" decision. Use ````suggestion` blocks for any code suggestions. + Provide your review as a GitHub single pull request review comment, not multiple comments. + + Use ````suggestion` blocks for any code suggestions. - Provide all your feedback as a single review comment, not multiple comments. - - Include an instruction at the end of your review that informs the author how to request a new review from you after they have addressed your feedback. + 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. # 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 ccaa3ca1899629a79e5b5c19477f031da5515b7d Mon Sep 17 00:00:00 2001 From: Cam Date: Fri, 17 Oct 2025 19:11:38 +0000 Subject: [PATCH 5/6] Update AGENTS.md to clarify Markdown newline requirement and add review instructions --- .github/workflows/claude-code-review.yml | 2 +- AGENTS.md | 11 +++++++++-- 2 files changed, 10 insertions(+), 3 deletions(-) diff --git a/.github/workflows/claude-code-review.yml b/.github/workflows/claude-code-review.yml index 0e6ce34b273e..6817c0082f1e 100644 --- a/.github/workflows/claude-code-review.yml +++ b/.github/workflows/claude-code-review.yml @@ -39,7 +39,7 @@ jobs: prompt: | 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 GitHub single pull request review comment, not multiple comments. + Provide your review as a single GitHub pull request review comment, not multiple comments. Use ````suggestion` blocks for any code suggestions. diff --git a/AGENTS.md b/AGENTS.md index 635cc83c5f89..7b052a4d890d 100644 --- a/AGENTS.md +++ b/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**. From 4f712e10a7168dd671d2e94b9ee3ab020498ebcc Mon Sep 17 00:00:00 2001 From: Cam Date: Fri, 17 Oct 2025 19:13:53 +0000 Subject: [PATCH 6/6] Clarify wording in copilot instructions for documentation review process --- .github/copilot-instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 41f5e92597d6..dc962c6cc3c7 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,3 +1,3 @@ Follow the repository's canonical instructions in `AGENTS.md`. If directory-specific `AGENTS.md` files exist, prefer the nearest one. -Use `.claude/commands/docs-review.md` for reviewing documentation changes. +Refer to `.claude/commands/docs-review.md` for reviewing documentation changes.