diff --git a/.claude/commands/docs-review.md b/.claude/commands/docs-review.md index b29926195fbf..1be7b849f829 100644 --- a/.claude/commands/docs-review.md +++ b/.claude/commands/docs-review.md @@ -1,24 +1,77 @@ --- -description: Review `pulumi/docs` changes for style, accuracy, and best practices +description: Review changes for style, accuracy, and Pulumi best practices. Context-sensitive in IDEs, or provide a PR number to review a PR from this repo. --- -# Usage -# Local: /docs-review [pr-number] -# CI: Automatically runs on PRs +# Documentation Review Command You will review documentation changes and provide feedback on style, accuracy, and best practices. -## For Local Usage: Determine Review Scope +## Instructions for Docs Review + +### Continuous Integration (CI) Context + +When running in CI (e.g., GitHub Actions), follow these efficiency guidelines to minimize token usage: + +1. Start by running `gh pr view --json title,body,files,additions,deletions` to get PR metadata +2. Get the full diff with `gh pr diff ` +3. Work primarily from the diff output - this is much more efficient than reading full files +4. Only use the Read tool on specific files when the diff doesn't provide enough context +5. Do NOT attempt to run `make serve`, `make lint`, or `make build` - these commands are not available in CI and will fail +6. Focus your review on the changed lines shown in the diff, not entire files +7. Use Grep sparingly - only when absolutely necessary to understand context + +After completing your review, post it to the PR by running: + +``` +gh pr comment --body "YOUR_REVIEW_CONTENT_HERE" +``` + +Your review should include: +- 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 + +Use the **Review Criteria** section below for your review. + +### Interactive Context (IDE or Chat) + +When running outside of CI, before beginning your review, you must determine the scope of changes to review: **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 +- Review the PR changes according to the criteria below. +- After completing your review, provide it in the conversation formatted appropriately for display in the terminal. + +**If no PR number is provided**, follow these steps IN ORDER: + +#### Step 1: Check for open files in IDE + +DO NOT RUN ANY COMMANDS YET. First check the conversation context: +- Look for system reminders about files open in the IDE +- If you find an open file mentioned, read that file and review it +- Stop and offer to review additional files if desired +- Skip to Step 4 if this applies -**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 +#### Step 2: Check for uncommitted changes + +If Step 1 didn't apply, check the gitStatus at the start of the conversation: +- Look for modified (M) or untracked (??) files in the git status +- If there are uncommitted changes, use `git diff` and `git status` to see what changed +- Review those specific files +- Skip to Step 4 if this applies + +#### Step 3: Compare against branch point + +ONLY if Steps 1 and 2 didn't apply: +- Use `git merge-base --fork-point master HEAD` to find the ancestor branch point +- Use `git diff $(git merge-base --fork-point master HEAD)...HEAD` to compare current branch against its immediate ancestor +- If `--fork-point` fails (no reflog), fall back to `git diff $(git merge-base master HEAD)...HEAD` +- Review all changed files in the branch + +#### Step 4: Perform the review + +Once scope is determined, review the changes according to the criteria below. Provide the review in the conversation formatted appropriately for display in the terminal. Include the scope of files reviewed in your summary and offer to review additional files if desired. ## Review Criteria @@ -58,22 +111,34 @@ 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: - - 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. +- **Role-Specific Review Guidelines** + - Documentation and blog/marketing materials have additional role-specific criteria below. + +### Role-Specific Review Guidelines + +#### Documentation + +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. + +#### Blogs or Marketing Materials + +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 index 07334f4504c8..eefce9135917 100644 --- a/.claude/commands/fix-issue.md +++ b/.claude/commands/fix-issue.md @@ -1,54 +1,100 @@ --- -description: Analyze a GitHub issue and create a comprehensive plan to fix it +description: Analyze a documentation issue and create a plan to fix it. --- # Usage -# /fix-issue -You will analyze GitHub issue #{{arg}} and create a comprehensive plan to fix it. +`/fix-issue ` -## Step 1: Gather Issue Details +Analyze GitHub issue #{{arg}} and create a comprehensive plan to address it. You are acting as a technical content engineer focused on improving documentation quality. -Use `gh issue view {{arg}}` to retrieve the full issue description, labels, comments, and any related context. +--- + +## Process + +### 1. Gather issue details + +Use `gh issue view {{arg}}` to retrieve the complete issue information: +- Read the full issue description to understand the problem +- Review labels to identify issue type (bug, enhancement, clarification, etc.) +- Read all comments and discussion to understand user pain points +- Note any related issues or PRs mentioned +- Identify the affected product area or documentation section + +### 2. Research current documentation + +Use semantic search and file tools to thoroughly investigate: +- Locate the specific documentation files mentioned or affected +- Read the current content to understand what's written today +- Identify what's missing, incorrect, outdated, or unclear +- Review related documentation pages for consistency and cross-references +- Search for similar patterns elsewhere in the docs that might have the same issue +- Check if code examples exist and whether they're tested + +### 3. Review guidelines + +Before proposing changes, verify compliance with: +- `AGENTS.md` — Repository conventions, build/test workflow, file movement rules, SEO requirements +- `STYLE-GUIDE.md` — Writing style, heading capitalization, code formatting, terminology +- Existing documentation patterns in the same section to maintain consistency +- Google Developer Documentation Style Guide for topics not covered in STYLE-GUIDE.md + +### 4. Create implementation plan + +Develop a detailed plan with these components: -## Step 2: Understand the Codebase +1. **Analysis** — Clearly explain: + - What the current documentation says (or doesn't say) + - Why it's problematic for users + - What impact this has on the user experience + - The root cause of the issue -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 +2. **Solution** — Describe the specific changes: + - New content to write (with outline of key points) + - Sections to restructure (with proposed new organization) + - Text to clarify (with examples of better wording) + - Outdated content to remove + - Code examples to add or fix -## Step 3: Consult Repository Guidelines +3. **Files to modify** — List exact file paths and locations: + - Full paths from repository root (e.g., `content/docs/clouds/aws/get-started.md`) + - Specific section headings where changes occur + - Line numbers if known -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 +4. **Implementation steps** — Break work into logical, ordered tasks: + - Update section headings and structure + - Rewrite or add explanatory content + - Add, update, or fix code examples in `/static/programs` + - Add cross-references and internal links + - Update or create diagrams/images (if needed - Be wary of images due to maintenance overhead) + - Add aliases if moving files (critical for SEO) + - Update related documentation for consistency -## Step 4: Formulate a Comprehensive Plan +5. **Verification** — Define how to validate the fix: + - Run `make lint` to check for errors + - Run `make serve` to preview rendering at http://localhost:1313 + - Test any code examples using program tests + - Verify all links work (internal and external) + - Confirm technical accuracy with subject matter experts if needed + - Check readability and clarity from user perspective -Create a detailed, step-by-step plan that includes: +6. **Considerations** — Note special requirements or impacts: + - Version-specific changes needed across multiple doc versions + - Related docs that need updates for consistency + - Breaking changes or deprecations to communicate + - SEO implications (aliases, redirects) if moving or deleting content + - Localization impacts if docs are translated + - Whether this reveals a larger documentation gap to address separately -1. **Analysis**: Clearly identify the desired outcome in the docs based on the issue description and current implementation -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 +### 5. Present for approval -## Step 5: Present the Plan +**IMPORTANT: Do NOT implement without user approval.** -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 +Present the complete plan to the user including: +- Clear, numbered steps in logical order +- Exact file paths with section headings or line numbers +- Specific commands that will be run (e.g., `make lint`, `make serve`) +- Any assumptions made or decisions that need user input +- Estimated scope (minor fix vs. major restructuring) -**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` +If the issue is ambiguous, ask clarifying questions before creating the plan. If multiple valid approaches exist, present options with pros/cons and ask for the user's preference. diff --git a/.github/workflows/claude-code-review.yml b/.github/workflows/claude-code-review.yml index 46035187e422..36b6817597f6 100644 --- a/.github/workflows/claude-code-review.yml +++ b/.github/workflows/claude-code-review.yml @@ -35,33 +35,12 @@ jobs: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} - # The canonical review criteria are defined in .claude/commands/docs-review.md. - # This prompt directs Claude to read that file as the source of truth. + # Invoke the docs-review slash command, which contains all review criteria and CI-specific guidance. + # See .claude/commands/docs-review.md for the complete review workflow. prompt: | - You are reviewing pull request #${{ github.event.pull_request.number }}. + You are running in a CI environment. - **CI Efficiency Guidelines (IMPORTANT - minimize token usage):** - 1. Start by running `gh pr view ${{ github.event.pull_request.number }} --json title,body,files,additions,deletions` to get PR metadata - 2. Get the full diff with `gh pr diff ${{ github.event.pull_request.number }}` - 3. Work primarily from the diff output - this is much more efficient than reading full files - 4. Only use the Read tool on specific files when the diff doesn't provide enough context - 5. Do NOT attempt to run `make serve`, `make lint`, or `make build` - these commands are not available in CI and will fail - 6. Focus your review on the changed lines shown in the diff, not entire files - 7. Use Grep sparingly - only when absolutely necessary to understand context - - **Review Criteria:** - Read `.claude/commands/docs-review.md` for the complete, canonical review criteria. Use those criteria to guide your review. - - **Posting Your Review:** - After completing your review, post it to the PR by running: - ``` - gh pr comment ${{ github.event.pull_request.number }} --body "YOUR_REVIEW_CONTENT_HERE" - ``` - - Your review should include: - - 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 + Review pull request #${{ github.event.pull_request.number }} by following the instructions in `.claude/commands/docs-review.md` under the "Continuous Integration (CI) Context" section. # 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