diff --git a/.claude/commands/docs-review.md b/.claude/commands/docs-review.md new file mode 100644 index 000000000000..e783d29336f7 --- /dev/null +++ b/.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. 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/copilot-instructions.md b/.github/copilot-instructions.md index e57ca0a4da6b..dc962c6cc3c7 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 +Refer to `.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..6817c0082f1e 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,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:*)"' 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**.