Enhance Claude Code slash command and review process

[CamSoper]

Tweaks to code review plumbing and quick issue fix slash command.

NOTE - The failure of the claude workflow is expected because I change that workflow with this PR.

[CamSoper]

@claude please review this PR.

[claude]

Claude finished @CamSoper's task —— View job

---

PR Review Complete

• Read changed files
• Analyze changes and compare with base
• Provide comprehensive review feedback

---

Review Summary

This PR makes solid improvements to the Claude Code slash commands and workflow configuration. The changes enhance clarity, provide better context-specific guidance, and simplify the CI workflow. Overall, the changes are well-structured and improve the developer experience. I have a few suggestions for further improvement.

.claude/commands/docs-review.md

Strengths

• Excellent reorganization: The new structure clearly separates CI context from interactive/IDE context, making it much easier to understand which instructions apply in each scenario.
• Better efficiency guidance: The CI section now has clear, numbered steps to minimize token usage.
• Improved interactive flow: The step-by-step process for determining review scope (open files → uncommitted changes → branch diff) is logical and well-documented.
• Enhanced formatting: The role-specific guidelines are now properly organized under dedicated subheadings.

Issues & Suggestions

Line 16: The instruction says "Get the full diff with gh pr diff <PR_NUMBER>" but should clarify the output format expectations.

Line 30: "Do not use line numbers from the diff" - This is good guidance, but could be clearer. Consider:

- Issues found with specific line numbers from the affected files (not the +/- line numbers from the diff output, but the actual line numbers in the source files)

Line 50-54: The instruction to "DO NOT RUN ANY COMMANDS YET" in Step 1 is strong, but the flow could be clearer. Consider adding emphasis:

#### Step 1: Check for open files in IDE

**DO NOT RUN ANY COMMANDS YET.** First check the conversation context:

Line 68: The fallback command git diff $(git merge-base master HEAD)...HEAD should use origin/master for consistency with repository conventions. Based on the gitStatus context showing recent commits, this appears to be a repository that tracks remote branches.

.claude/commands/fix-issue.md

Strengths

• Much clearer structure: The numbered process with clear subsections is a significant improvement over the previous step-by-step format.
• Better separation of concerns: Each phase (gather, research, review guidelines, create plan, present) is distinct and actionable.
• Comprehensive planning components: The 6-part plan structure (Analysis, Solution, Files, Steps, Verification, Considerations) ensures thorough thinking.
• Good emphasis on approval: The "IMPORTANT: Do NOT implement without user approval" callout is appropriately prominent.

Issues & Suggestions

Line 8: Good improvement to clarify the role ("technical content engineer focused on improving documentation quality").

Line 40: Reference to AGENTS.md mentions "file movement rules" - verify this aligns with the actual content in AGENTS.md (which does cover this with the SEO-critical section).

Line 69: "Be wary of images due to maintenance overhead" is good advice but could be more specific:

- Update or create diagrams/images (if needed - images require maintenance as products evolve; prefer text explanations when possible)

Line 86: "Whether this reveals a larger documentation gap to address separately" - excellent addition that encourages systemic thinking.

Minor: The file refers to "content/docs/clouds/aws/get-started.md" as an example path (line 60), but doesn't verify this path structure exists in the actual repository. This is fine as an example, but could note it's illustrative.

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

Strengths

• Significant simplification: Removing the inline documentation and deferring to .claude/commands/docs-review.md reduces duplication and maintenance burden.
• Clearer comments: The comment on lines 38-39 explains what's happening without excessive detail.
• Better separation: The prompt now clearly states the context ("You are running in a CI environment") upfront.

Issues & Suggestions

Line 41: The prompt says "You are running in a CI environment." This is good context, but consider whether this is necessary given that the docs-review.md file should detect CI context automatically. However, it's probably useful as explicit context, so this is fine.

Line 43: The instruction references "the 'Continuous Integration (CI) Context' section" - verify this exact heading exists in docs-review.md. ✓ Confirmed it does (line 11 of docs-review.md).

Line 48: The claude_args line is well-structured and limits tools appropriately for CI context.

Consider: The workflow still fetches with fetch-depth: 1 (line 29). This is efficient, but verify that gh pr diff works correctly with shallow clones. This should be fine since gh uses the GitHub API, not local git history.

Cross-File Consistency

Positive: All three files work together cohesively. The workflow invokes the command, which contains the complete instructions. Good architecture.

Minor inconsistency: The docs-review.md file mentions both master (line 68) and master HEAD in git commands, but the repository conventions (based on gitStatus) suggest using origin/master as the remote tracking branch. Consider standardizing on origin/master throughout.

Recommendations

1. High priority: Clarify the line number guidance in docs-review.md:30 to avoid confusion between diff line numbers and source file line numbers.

2. Medium priority: Update git commands in docs-review.md to use origin/master for consistency with repository conventions.

3. Low priority: Enhance the image guidance in fix-issue.md:69 to be more specific about why images should be used sparingly.

4. Optional: Consider adding a brief example in docs-review.md showing the difference between diff line numbers and source file line numbers.

Conclusion

These changes represent a meaningful improvement to the Claude Code integration. The reorganization makes the commands much more maintainable and easier to use. The few suggestions above are minor refinements that would further enhance clarity.

Great work on simplifying the CI workflow and creating better structure in the slash command documentation!

---

If you'd like me to implement any of these suggestions or review additional aspects of this PR, please mention me (@claude) with your request.

[pulumi-bot]

Your site preview for commit c99268e is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16410-c99268e6.s3-website.us-west-2.amazonaws.com.