Skip to content

Commit a8612ca

Browse files
CamSoperCamSoper
authored
Claude Code slash command and automated review refinements (#16410)
1 parent b8cc0a2 commit a8612ca

File tree

3 files changed

+181
-91
lines changed

3 files changed

+181
-91
lines changed

‎.claude/commands/docs-review.md‎

Lines changed: 94 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,77 @@
11
---
2-
description: Review `pulumi/docs` changes for style, accuracy, and best practices
2+
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.
33
---
44

5-
# Usage
6-
# Local: /docs-review [pr-number]
7-
# CI: Automatically runs on PRs
5+
# Documentation Review Command
86

97
You will review documentation changes and provide feedback on style, accuracy, and best practices.
108

11-
## For Local Usage: Determine Review Scope
9+
## Instructions for Docs Review
10+
11+
### Continuous Integration (CI) Context
12+
13+
When running in CI (e.g., GitHub Actions), follow these efficiency guidelines to minimize token usage:
14+
15+
1. Start by running `gh pr view <PR_NUMBER> --json title,body,files,additions,deletions` to get PR metadata
16+
2. Get the full diff with `gh pr diff <PR_NUMBER>`
17+
3. Work primarily from the diff output - this is much more efficient than reading full files
18+
4. Only use the Read tool on specific files when the diff doesn't provide enough context
19+
5. Do NOT attempt to run `make serve`, `make lint`, or `make build` - these commands are not available in CI and will fail
20+
6. Focus your review on the changed lines shown in the diff, not entire files
21+
7. Use Grep sparingly - only when absolutely necessary to understand context
22+
23+
After completing your review, post it to the PR by running:
24+
25+
```
26+
gh pr comment <PR_NUMBER> --body "YOUR_REVIEW_CONTENT_HERE"
27+
```
28+
29+
Your review should include:
30+
- Issues found with specific line numbers from the affected files. Do not use line numbers from the diff.
31+
- Constructive suggestions using suggestion code fence formatting blocks
32+
- An instruction to mention you (@claude) if the author wants additional reviews or fixes
33+
34+
Use the **Review Criteria** section below for your review.
35+
36+
### Interactive Context (IDE or Chat)
37+
38+
When running outside of CI, before beginning your review, you must determine the scope of changes to review:
1239

1340
**If a PR number is provided** ({{arg}}):
1441
- Use `gh pr view {{arg}}` to retrieve the PR title, description, and metadata
1542
- Use `gh pr diff {{arg}}` to get the full diff of changes
16-
- Review the PR changes according to the criteria below
43+
- Review the PR changes according to the criteria below.
44+
- After completing your review, provide it in the conversation formatted appropriately for display in the terminal.
45+
46+
**If no PR number is provided**, follow these steps IN ORDER:
47+
48+
#### Step 1: Check for open files in IDE
49+
50+
DO NOT RUN ANY COMMANDS YET. First check the conversation context:
51+
- Look for system reminders about files open in the IDE
52+
- If you find an open file mentioned, read that file and review it
53+
- Stop and offer to review additional files if desired
54+
- Skip to Step 4 if this applies
1755

18-
**If no PR number is provided**:
19-
- Use `git status` to check for uncommitted changes
20-
- Use `git diff master...HEAD` to compare current branch against master
21-
- Review the changes according to the criteria below
56+
#### Step 2: Check for uncommitted changes
57+
58+
If Step 1 didn't apply, check the gitStatus at the start of the conversation:
59+
- Look for modified (M) or untracked (??) files in the git status
60+
- If there are uncommitted changes, use `git diff` and `git status` to see what changed
61+
- Review those specific files
62+
- Skip to Step 4 if this applies
63+
64+
#### Step 3: Compare against branch point
65+
66+
ONLY if Steps 1 and 2 didn't apply:
67+
- Use `git merge-base --fork-point master HEAD` to find the ancestor branch point
68+
- Use `git diff $(git merge-base --fork-point master HEAD)...HEAD` to compare current branch against its immediate ancestor
69+
- If `--fork-point` fails (no reflog), fall back to `git diff $(git merge-base master HEAD)...HEAD`
70+
- Review all changed files in the branch
71+
72+
#### Step 4: Perform the review
73+
74+
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.
2275

2376
## Review Criteria
2477

@@ -58,22 +111,34 @@ Always provide relevant line numbers for any issues you identify.
58111
- **SEO**:
59112
- Check that page titles and descriptions are SEO-friendly.
60113
- Verify URL structure follows conventions.
61-
- When reviewing **Documentation**, serve the role of a professional technical writer. Review for:
62-
- Clarity and conciseness.
63-
- Logical flow and structure.
64-
- No jargon unless defined.
65-
- Avoid passive voice.
66-
- Avoid overly complex sentences. Shorter is usually better.
67-
- Avoid superlatives and vague qualifiers.
68-
- Avoid unnecessary filler words or sentences.
69-
- Be specific and provide examples.
70-
- Use consistent terminology.
71-
- When reviewing **Blog posts or marketing materials**, serve the role of a professional technical blogger. Review for:
72-
- Clear, engaging titles.
73-
- Strong opening that hooks the reader.
74-
- Clear structure with headings and subheadings.
75-
- Concise paragraphs (3-4 sentences max).
76-
- Use of lists and bullet points for readability.
77-
- Reject filler, vague generalities, or AI-generated slop.
78-
- Avoid clickbait phrasing.
79-
- Clear call-to-action at the end.
114+
- **Role-Specific Review Guidelines**
115+
- Documentation and blog/marketing materials have additional role-specific criteria below.
116+
117+
### Role-Specific Review Guidelines
118+
119+
#### Documentation
120+
121+
When reviewing **Documentation**, serve the role of a professional technical writer. Review for:
122+
123+
- Clarity and conciseness.
124+
- Logical flow and structure.
125+
- No jargon unless defined.
126+
- Avoid passive voice.
127+
- Avoid overly complex sentences. Shorter is usually better.
128+
- Avoid superlatives and vague qualifiers.
129+
- Avoid unnecessary filler words or sentences.
130+
- Be specific and provide examples.
131+
- Use consistent terminology.
132+
133+
#### Blogs or Marketing Materials
134+
135+
When reviewing **Blog posts or marketing materials**, serve the role of a professional technical blogger. Review for:
136+
137+
- Clear, engaging titles.
138+
- Strong opening that hooks the reader.
139+
- Clear structure with headings and subheadings.
140+
- Concise paragraphs (3-4 sentences max).
141+
- Use of lists and bullet points for readability.
142+
- Reject filler, vague generalities, or AI-generated slop.
143+
- Avoid clickbait phrasing.
144+
- Clear call-to-action at the end.

‎.claude/commands/fix-issue.md‎

Lines changed: 83 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,54 +1,100 @@
11
---
2-
description: Analyze a GitHub issue and create a comprehensive plan to fix it
2+
description: Analyze a documentation issue and create a plan to fix it.
33
---
44

55
# Usage
6-
# /fix-issue <issue-number>
76

8-
You will analyze GitHub issue #{{arg}} and create a comprehensive plan to fix it.
7+
`/fix-issue <issue-number>`
98

10-
## Step 1: Gather Issue Details
9+
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.
1110

12-
Use `gh issue view {{arg}}` to retrieve the full issue description, labels, comments, and any related context.
11+
---
12+
13+
## Process
14+
15+
### 1. Gather issue details
16+
17+
Use `gh issue view {{arg}}` to retrieve the complete issue information:
18+
- Read the full issue description to understand the problem
19+
- Review labels to identify issue type (bug, enhancement, clarification, etc.)
20+
- Read all comments and discussion to understand user pain points
21+
- Note any related issues or PRs mentioned
22+
- Identify the affected product area or documentation section
23+
24+
### 2. Research current documentation
25+
26+
Use semantic search and file tools to thoroughly investigate:
27+
- Locate the specific documentation files mentioned or affected
28+
- Read the current content to understand what's written today
29+
- Identify what's missing, incorrect, outdated, or unclear
30+
- Review related documentation pages for consistency and cross-references
31+
- Search for similar patterns elsewhere in the docs that might have the same issue
32+
- Check if code examples exist and whether they're tested
33+
34+
### 3. Review guidelines
35+
36+
Before proposing changes, verify compliance with:
37+
- `AGENTS.md` — Repository conventions, build/test workflow, file movement rules, SEO requirements
38+
- `STYLE-GUIDE.md` — Writing style, heading capitalization, code formatting, terminology
39+
- Existing documentation patterns in the same section to maintain consistency
40+
- Google Developer Documentation Style Guide for topics not covered in STYLE-GUIDE.md
41+
42+
### 4. Create implementation plan
43+
44+
Develop a detailed plan with these components:
1345

14-
## Step 2: Understand the Codebase
46+
1. **Analysis** — Clearly explain:
47+
- What the current documentation says (or doesn't say)
48+
- Why it's problematic for users
49+
- What impact this has on the user experience
50+
- The root cause of the issue
1551

16-
Based on the issue details:
17-
- Search for relevant files, functions, or patterns mentioned in the issue
18-
- Understand the current implementation and identify the root cause
19-
- Review related code sections to understand dependencies and impacts
20-
- Check for similar issues or related functionality
52+
2. **Solution** — Describe the specific changes:
53+
- New content to write (with outline of key points)
54+
- Sections to restructure (with proposed new organization)
55+
- Text to clarify (with examples of better wording)
56+
- Outdated content to remove
57+
- Code examples to add or fix
2158

22-
## Step 3: Consult Repository Guidelines
59+
3. **Files to modify** — List exact file paths and locations:
60+
- Full paths from repository root (e.g., `content/docs/clouds/aws/get-started.md`)
61+
- Specific section headings where changes occur
62+
- Line numbers if known
2363

24-
Review and follow:
25-
- `AGENTS.md` - Repository conventions and build/test workflow
26-
- `STYLE-GUIDE.md` - Style and formatting requirements
27-
- Related documentation to ensure any proposed changes align with existing patterns
64+
4. **Implementation steps** — Break work into logical, ordered tasks:
65+
- Update section headings and structure
66+
- Rewrite or add explanatory content
67+
- Add, update, or fix code examples in `/static/programs`
68+
- Add cross-references and internal links
69+
- Update or create diagrams/images (if needed - Be wary of images due to maintenance overhead)
70+
- Add aliases if moving files (critical for SEO)
71+
- Update related documentation for consistency
2872

29-
## Step 4: Formulate a Comprehensive Plan
73+
5. **Verification** — Define how to validate the fix:
74+
- Run `make lint` to check for errors
75+
- Run `make serve` to preview rendering at http://localhost:1313
76+
- Test any code examples using program tests
77+
- Verify all links work (internal and external)
78+
- Confirm technical accuracy with subject matter experts if needed
79+
- Check readability and clarity from user perspective
3080

31-
Create a detailed, step-by-step plan that includes:
81+
6. **Considerations** — Note special requirements or impacts:
82+
- Version-specific changes needed across multiple doc versions
83+
- Related docs that need updates for consistency
84+
- Breaking changes or deprecations to communicate
85+
- SEO implications (aliases, redirects) if moving or deleting content
86+
- Localization impacts if docs are translated
87+
- Whether this reveals a larger documentation gap to address separately
3288

33-
1. **Analysis**: Clearly identify the desired outcome in the docs based on the issue description and current implementation
34-
1. **Proposed Solution**: Describe the approach to fix the issue
35-
1. **Files to Modify**: List specific files and line numbers that need changes
36-
1. **Implementation Steps**: Break down the work into logical, sequential tasks
37-
1. **Testing Strategy**: How to verify the fix works correctly
38-
1. **Edge Cases**: Identify any edge cases or potential complications
39-
1. **Verification Steps**: Commands to run (lint, build, test) to ensure the fix is complete
89+
### 5. Present for approval
4090

41-
## Step 5: Present the Plan
91+
**IMPORTANT: Do NOT implement without user approval.**
4292

43-
Present the plan to the user using the `ExitPlanMode` tool. Include:
44-
- Clear, concise steps
45-
- Relevant file paths with line numbers
46-
- Commands that will be run
47-
- Any assumptions or decisions that may need user input
93+
Present the complete plan to the user including:
94+
- Clear, numbered steps in logical order
95+
- Exact file paths with section headings or line numbers
96+
- Specific commands that will be run (e.g., `make lint`, `make serve`)
97+
- Any assumptions made or decisions that need user input
98+
- Estimated scope (minor fix vs. major restructuring)
4899

49-
**Important**:
50-
- Do NOT start implementing without user approval
51-
- If the issue is ambiguous, ask clarifying questions before planning
52-
- If multiple approaches are viable, present options and ask for the user's preference
53-
- Be specific about what will change and why
54-
- Ensure all changes comply with `STYLE-GUIDE.md` and `AGENTS.md`
100+
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.

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

Lines changed: 4 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -35,33 +35,12 @@ jobs:
3535
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
3636
with:
3737
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
38-
# The canonical review criteria are defined in .claude/commands/docs-review.md.
39-
# This prompt directs Claude to read that file as the source of truth.
38+
# Invoke the docs-review slash command, which contains all review criteria and CI-specific guidance.
39+
# See .claude/commands/docs-review.md for the complete review workflow.
4040
prompt: |
41-
You are reviewing pull request #${{ github.event.pull_request.number }}.
41+
You are running in a CI environment.
4242
43-
**CI Efficiency Guidelines (IMPORTANT - minimize token usage):**
44-
1. Start by running `gh pr view ${{ github.event.pull_request.number }} --json title,body,files,additions,deletions` to get PR metadata
45-
2. Get the full diff with `gh pr diff ${{ github.event.pull_request.number }}`
46-
3. Work primarily from the diff output - this is much more efficient than reading full files
47-
4. Only use the Read tool on specific files when the diff doesn't provide enough context
48-
5. Do NOT attempt to run `make serve`, `make lint`, or `make build` - these commands are not available in CI and will fail
49-
6. Focus your review on the changed lines shown in the diff, not entire files
50-
7. Use Grep sparingly - only when absolutely necessary to understand context
51-
52-
**Review Criteria:**
53-
Read `.claude/commands/docs-review.md` for the complete, canonical review criteria. Use those criteria to guide your review.
54-
55-
**Posting Your Review:**
56-
After completing your review, post it to the PR by running:
57-
```
58-
gh pr comment ${{ github.event.pull_request.number }} --body "YOUR_REVIEW_CONTENT_HERE"
59-
```
60-
61-
Your review should include:
62-
- Issues found with specific line numbers from the affected files. Do not use line numbers from the diff.
63-
- Constructive suggestions using suggestion code fence formatting blocks
64-
- An instruction to mention you (@claude) if the author wants additional reviews or fixes
43+
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.
6544
6645
# See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
6746
# or https://docs.anthropic.com/en/docs/claude-code/sdk#command-line for available options

0 commit comments

Comments
 (0)