Back to catalog

github-pr-review

Provides comprehensive GitHub PR review with inline suggested changes that can be applied via GitHub's web UI "Commit suggestion" button. Triggers when reviewing PRs, analyzing code changes, or when user requests PR review with applicable suggestions.

• Category: discovered
• Tags: github, community
• Version: 1.0.0
• Author: walid
• Downloads: 0
• GitHub stars: 1
• Updated: 2025-11-21

• Source: The1Studio/theone-training-skills

Download the latest version (v1.0.0) from this page.

SKILL.md

---
name: github-pr-review
description: Provides comprehensive GitHub PR review with inline suggested changes that can be applied via GitHub's web UI "Commit suggestion" button. Triggers when reviewing PRs, analyzing code changes, or when user requests PR review with applicable suggestions.
---

# GitHub PR Review with Suggested Changes

## Skill Purpose

This skill enables comprehensive GitHub pull request reviews with **actionable suggested changes** that developers can apply directly through GitHub's web UI using the "Commit suggestion" button.

**Key Features:**
- Code review against TheOne Studio standards
- Inline suggested changes using ````suggestion` blocks
- GitHub API integration for programmatic review comments
- Batch suggestion support for efficient fixes
- Complete file replacements when needed

## When This Skill Triggers

**Automatically triggers when:**
- User asks to "review PR" or "review pull request"
- User provides a GitHub PR URL for review
- User asks to "check PR" or "analyze PR changes"
- User requests code review with suggestions
- User asks "help review this PR"

**Manual trigger:**
- User explicitly invokes the skill with `/github-pr-review`

## Quick Reference

### GitHub Suggested Changes Syntax

```markdown
Add nullable directive at the top of the file.

\`\`\`suggestion
#nullable enable

namespace YourNamespace
\`\`\`
```

**Result:** Shows a "Commit suggestion" button in GitHub UI that applies the change when clicked.

## How It Works

### Step 1: Fetch PR Details

```bash
# Get PR information
gh pr view <PR_NUMBER> --repo <OWNER/REPO> --json title,body,files,commits

# Get PR diff
gh pr diff <PR_NUMBER> --repo <OWNER/REPO>
```

### Step 2: Analyze Code Changes

- Review against coding standards (e.g., `theone-unity-standards`)
- Identify issues by severity (Critical, Important, Suggestions)
- Categorize issues by file and line number

### Step 3: Create Inline Suggestions

**Use GitHub API to add inline comments with suggestions:**

```bash
# Get latest commit ID
COMMIT_ID=$(gh pr view <PR> --repo <REPO> --json commits --jq '.commits[-1].oid')

# Add inline suggestion comment
gh api \
  --method POST \
  -H "Accept: application/vnd.github+json" \
  /repos/<OWNER>/<REPO>/pulls/<PR_NUMBER>/comments \
  -f body="<suggestion text with \`\`\`suggestion block>" \
  -f commit_id="$COMMIT_ID" \
  -f path="<file_path>" \
  -F position=<line_number>
```

### Step 4: Add Summary Comment

Add a general comment explaining:
- Number of suggestions added
- How to apply suggestions (individual or batch)
- What issues will be resolved

## Suggestion Types

### 1. Single-Line Suggestions

```markdown
Fix access modifier.

\`\`\`suggestion
public sealed class MyClass
\`\`\`
```

### 2. Multi-Line Suggestions

```markdown
Add nullable directive and fix class.

\`\`\`suggestion
#nullable enable

namespace MyNamespace
{
    public sealed class MyClass
    {
        // class body
    }
}
\`\`\`
```

### 3. Complete File Replacements

For major refactoring, provide complete fixed file in expandable section:

```markdown
<details>
<summary>Click to expand: Complete fixed file</summary>

\`\`\`csharp
// entire file content
\`\`\`
</details>
```

## Best Practices

### ✅ DO:

1. **Use inline suggestions for fixable issues**
   - Syntax errors, formatting issues
   - Missing keywords, modifiers
   - Simple refactoring

2. **Add suggestions at correct line positions**
   - Use `gh pr diff` to find exact line numbers
   - Use `position` parameter (diff position, not file line number)

3. **Group related changes**
   - Combine related fixes in one suggestion block
   - Example: Add `#nullable enable` + `sealed` keyword together

4. **Provide context**
   - Explain WHY the change is needed
   - Reference coding standards or best practices

5. **Use batch suggestions for multiple fixes**
   - Tell developer about "Add suggestion to batch" option
   - Allows applying all suggestions in one commit

### ❌ DON'T:

1. **Don't suggest changes for non-fixable issues**
   - Architectural problems requiring discussion
   - Design pattern changes
   - Use regular comments for these

2. **Don't create overlapping suggestions**
   - Each suggestion should apply cleanly
   - Avoid suggesting same lines multiple times

3. **Don't suggest changes without explanation**
   - Always include WHY the change is needed
   - Link to relevant documentation or standards

## GitHub API Position Calculation

**Important:** The `position` parameter is the **diff position**, not the file line number.

```bash
# Get diff to see positions
gh pr diff <PR_NUMBER> --repo <OWNER/REPO>

# Position starts at 1 for first changed line
# Increments for each line in the diff (context + changes)
```

**Example:**
```diff
@@ -0,0 +1,10 @@
+namespace MyNamespace    # position: 1
+{                        # position: 2
+    public class Foo     # position: 3
+    {                    # position: 4
```

## Common Review Patterns

### Pattern 1: Missing Nullable Directive

**Issue:** Missing `#nullable enable`
**Location:** Line 1 (before namespace)
**Position:** Usually 1

```markdown
Add \`#nullable enable\` directive at the top of the file.

\`\`\`suggestion
#nullable enable

namespace YourNamespace
\`\`\`
```

### Pattern 2: Missing Sealed Keyword

**Issue:** Class should be `sealed`
**Location:** Class declaration line
**Position:** Find in diff

```markdown
Add \`sealed\` keyword to prevent inheritance.

\`\`\`suggestion
    public sealed class YourClass
\`\`\`
```

### Pattern 3: Fields to Properties

**Issue:** Public fields instead of properties
**Location:** Field declaration lines
**Position:** Find in diff

```markdown
Convert field to property with getter.

\`\`\`suggestion
        public Dictionary<string, int> MyProperty { get; } = new();
\`\`\`
```

### Pattern 4: Remove Region Comments

**Issue:** Using `#region` / `#endregion`
**Location:** Region block
**Position:** Find in diff

```markdown
Remove \`#region\` comments - code should be self-organizing.

\`\`\`suggestion
        private readonly UserDataManager userDataManager;

        public MyController(UserDataManager userDataManager)
        {
            this.userDataManager = userDataManager;
        }
\`\`\`
```

## Complete Workflow Example

```bash
# 1. Get PR details
PR_NUMBER=984
REPO="The1Studio/TheOneFeature"
COMMIT_ID=$(gh pr view $PR_NUMBER --repo $REPO --json commits --jq '.commits[-1].oid')

# 2. Review code (use theone-unity-standards skill)
# ... analyze code against standards ...

# 3. Add suggestion for file1
gh api \
  --method POST \
  -H "Accept: application/vnd.github+json" \
  /repos/$REPO/pulls/$PR_NUMBER/comments \
  -f body="Add \`#nullable enable\` directive.

\`\`\`suggestion
#nullable enable

namespace MyNamespace
\`\`\`" \
  -f commit_id="$COMMIT_ID" \
  -f path="path/to/file1.cs" \
  -F position=1

# 4. Add suggestion for file2
# ... repeat for each issue ...

# 5. Add summary comment
gh pr comment $PR_NUMBER --repo $REPO --body "## ✅ Suggestions Ready

I've added 6 inline suggestions. Go to Files Changed tab and click 'Commit suggestion' on each, or use 'Add suggestion to batch' to apply all at once."
```

## Integration with Other Skills

**Works best with:**
- `theone-unity-standards` - For Unity C# code reviews
- `code-reviewer` - For general code quality analysis
- `docs-seeker` - For finding latest library documentation

**Example workflow:**
1. User provides PR URL
2. Trigger `theone-unity-standards` to analyze code
3. Use `github-pr-review` to create suggested changes
4. Developer applies suggestions via GitHub UI

## Troubleshooting

### Issue: "404 Not Found" when creating suggestion

**Cause:** Wrong `position` value
**Fix:** Verify position in diff output

```bash
gh pr diff <PR> --repo <REPO> | less
# Count lines from @@ hunk header
```

### Issue: Suggestion doesn't show "Commit suggestion" button

**Cause:** Invalid ````suggestion` syntax
**Fix:** Ensure proper markdown formatting:
- Three backticks
- Word "suggestion" (lowercase)
- Proper code indentation inside block

### Issue: Suggestion applies but breaks code

**Cause:** Incorrect indentation or incomplete context
**Fix:**
- Match existing file indentation exactly
- Include enough context lines
- Test suggestion locally first

## Summary

This skill automates comprehensive GitHub PR reviews with actionable suggestions:

1. ✅ Fetches PR details and diff
2. ✅ Analyzes code against standards
3. ✅ Creates inline suggestions with ````suggestion` blocks
4. ✅ Uses GitHub API for programmatic comments
5. ✅ Enables one-click fixes via GitHub UI

**Result:** Faster, more efficient PR reviews with instant applicability.

## References

- [GitHub Suggested Changes](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request)
- [GitHub API - PR Review Comments](https://docs.github.com/en/rest/pulls/comments)
- [TheOne Studio Standards](../theone-unity-standards/SKILL.md)