review-pr

What this skill does

# PR Review Tour Guide

Generate a structured, guided tour of a Pull Request that helps reviewers understand changes efficiently. Acts as a knowledgeable guide walking someone through a codebase change.

## Automatic Invocation Triggers

Claude will invoke this skill when you:
- Ask to "review PR #123" or "review this PR"
- Say "walk me through this PR"
- Request "PR tour guide" or "explain this PR"
- Ask "what should I look for in this PR"
- Say "create a PR review walkthrough"
- Request "review and approve PR #123" (triggers review with approval workflow)

## Overview

This skill creates a guided tour of PR changes that:
- **Orders files logically** (as GitHub UI shows - depth-first with folders before files)
- **Groups review points** into digestible stops (no more than ~25 lines per stop)
- **Provides context** about why code exists and its history
- **Highlights review priorities** (what needs rigorous review vs. rubber-stamp)
- **Uses landmarks** (line numbers, class/function names) for easy navigation

## Input Requirements

The skill needs:
1. **PR number** and **repository** (e.g., "PR #3091 in altimate-backend")
2. OR a **PR URL** (e.g., "https://github.com/owner/repo/pull/3091")
3. Optionally, a **linked issue/ticket** for context comparison (GitHub Issues, Jira, Linear, etc.)

## Operation Mode Detection

Before starting the review, detect the operation context to determine default behavior:

### Detecting Operation Mode

**CLI Mode Indicators** (weight toward local display first):
- Running in Claude Code CLI directly
- User is interactively typing commands
- Terminal/TTY is available
- No delegation context detected

**Pass-Through/Delegated Mode Indicators** (weight toward inline GitHub comments):
- Request came via OpenClaw or similar delegation tool
- Request came from automation/CI context
- Request mentions "post comments" or "leave feedback on PR"
- No interactive terminal available

### Default Behavior by Mode

| Mode | Default Action | Rationale |
|------|---------------|-----------|
| CLI (interactive) | Display review locally first, then offer to post | User can review and edit before posting |
| Pass-through/Delegated | Post inline comments directly (if confident) | Automation context benefits from persistent comments |

**If unsure about mode:** Ask the user: "Would you like me to display the review here first, or post comments directly on the PR?"

## Workflow

### Step 1: Gather PR Information

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

# Get the full diff
gh pr diff <PR_NUMBER> --repo <OWNER/REPO>

# If linked issue/ticket provided, fetch details based on tracker type:
# - GitHub Issues: gh issue view <ISSUE_NUMBER> --repo <OWNER/REPO>
# - Jira: Use mcp__atlassian__getJiraIssue or API
# - Linear: Use Linear MCP or API
# - Other trackers: Use appropriate MCP or API
```

### Step 2: Analyze and Order Files

Order files using depth-first traversal (folders before files):
1. At each directory level, process subdirectories first (alphabetically), recursively
2. Then process files in the current directory (alphabetically)
3. This ensures reviewers see related nested changes together before sibling files

**Example ordering:**
```
app/
  models/
    user.py          # 1. Deepest nested first
    account.py       # 2. Same level, alphabetical
  services/
    auth.py          # 3. Next subdirectory
  utils.py           # 4. Files in app/ after all subdirectories
config/
  settings.py        # 5. Next root subdirectory
main.py              # 6. Root-level files last
```

Create a summary table:

```markdown
| # | File | +/- | Purpose |
|---|------|-----|---------|
| 1 | `path/to/file1.py` | +50/-10 | Brief purpose |
| 2 | `path/to/file2.py` | +20/-5 | Brief purpose |
```

### Step 3: Generate Tour Stops

For each significant change, create a "tour stop" with:

```markdown
### Stop N: [Descriptive Title] (Lines X-Y)

[Code snippet or reference]

**Context:** Why this code exists, what problem it solves

**Notice:** What the reviewer should observe about this change

**Review:**
- [Checkbox] Items that need careful review
- [Warning] Potential issues or risks
- [Check] Items that look good
```

### Step 4: Prioritize Review Areas

Use these markers:
- **RIGOROUSLY REVIEW** - Security, data integrity, breaking changes
- **Notice** - Important but straightforward changes
- **Context** - Background information
- **Warning** - Potential issues or edge cases

### Step 5: Create Summary Checklist

End with actionable review checklist:

```markdown
## Summary Checklist

| Area | Status | Action |
|------|--------|--------|
| Core logic | [Status] | [Action needed] |
| Error handling | [Status] | [Action needed] |
| Tests | [Status] | [Action needed] |
```

## Output Format

```markdown
# PR #[NUMBER] Review Tour Guide

## File Order (as shown in GitHub UI)

| # | File | +/- | Purpose |
|---|------|-----|---------|
| 1 | `file1.py` | +50 | Description |

---

## File 1: `path/to/file1.py`

**This is the [main/supporting] file. [Brief overview].**

---

### Stop 1: [Section Title] (Lines X-Y)

```python
# Relevant code snippet (abbreviated)
```

**Context:** [Why this exists]

**Notice:** [What to observe]

**Review:**
- [Review point]
- [Warning if any]

---

### Stop 2: [Next Section] (Lines A-B)

[Continue pattern...]

---

## Summary Checklist

| Area | Status | Action |
|------|--------|--------|
| Item | Status | Action |
```

## Tour Stop Guidelines

### Grouping Rules

1. **One function/class per stop** - Don't mix unrelated changes
2. **Max ~25 lines of code** - Keep stops digestible
3. **Group related small changes** - Multiple one-liners can share a stop
4. **Separate concerns** - Config changes vs. logic changes vs. tests

### What to Call Out

**Always mention:**
- Breaking changes to public APIs
- Security-sensitive code (auth, crypto, user input)
- Database schema changes
- External service integrations
- Error handling patterns
- Performance implications

**Highlight patterns:**
- Code that duplicates existing functionality
- Missing error handling
- Hardcoded values that should be configurable
- Tests that don't actually test the change

### Context Sources

Provide context from:
- Linked issue/ticket description (GitHub Issues, Jira, Linear, etc.)
- PR description and commits
- Related code in the codebase
- Previous implementations being replaced

## Example Tour Stop

```markdown
### Stop 7: Row Processor - Column Count (Lines 802-830) - CRITICAL BUG FIX

```python
def _process_column_count_row(self, row: dict) -> dict:
    table_rk = _get_snowflake_table_rk(
        table, self.is_instance_default, self.instance_id
    )
    column_rk = _get_column_rk_from_table_rk(table_rk, column) if table_rk else None
    #                                                         ^^^^^^^^^^^^^^^^^^^^^^
```

**Context:** This is the bug fix from commit `a187cd4c`. Previously, when `table_rk` was `None`, `_get_column_rk_from_table_rk(None, column)` would return `"none/column_name"` - a string that bypassed skip logic.

**Review:**
- Good fix - now `column_rk` is `None` when `table_rk` is `None`
- **Verify:** Does the original class have this same bug? If so, should it be fixed there too?
```

## Comparison with Linked Issue/Ticket

When a linked issue or ticket is provided (GitHub Issue, Jira, Linear, etc.):

### Step 1: Detect and Fetch Ticket Details

**GitHub Issues:**
```bash
gh issue view <ISSUE_NUMBER> --repo <OWNER/REPO> --json title,body,labels,assignees
```

**Jira:**
- Use Atlassian MCP: `mcp__atlassian__getJiraIssue`
- Or Jira REST API

**Linear:**
- Use Linear MCP or GraphQL API
- Extract issue details from Linear URL

**Other Trackers:**
- Use appropriate MCP integration if available
- Fall back to URL/description provided by user

### Step 2: Extract and Compare Requirements

1. **Parse requirements** from issue/ticket description