code-review

What this skill does

# Multi-Perspective PR Code Review

Perform a comprehensive code review on a GitHub pull request by dispatching multiple specialized reviewer agents in parallel, each analyzing from a different perspective with a clean context. Aggregate all findings into a single GitHub PR review with line-specific comments.

## Review Perspectives

Eight reviewer agents analyze the PR simultaneously:

| Agent | Model | Focus |
|-------|-------|-------|
| `logic-reviewer` | sonnet | Bugs, edge cases, error handling, race conditions |
| `design-reviewer` | sonnet | Code structure, naming, SOLID, readability |
| `security-reviewer` | sonnet | Injection, auth issues, data exposure, OWASP |
| `performance-reviewer` | haiku | Algorithmic complexity, memory, N+1 queries |
| `convention-reviewer` | haiku | CLAUDE.md compliance, project conventions |
| `git-history-reviewer` | haiku | Git blame, commit history, regression risk |
| `pr-history-reviewer` | haiku | Past PRs and review comments on same files |
| `docs-reviewer` | haiku | Missing or outdated documentation for changed code |

## Helper Scripts

| Script | Purpose |
|--------|---------|
| `scripts/fetch-pr-diff.sh` | Fetch PR diff and metadata |
| `scripts/post-review.sh` | Post a combined review with line comments |

## Workflow

### Step 1: Fetch PR Data

Fetch the PR diff and metadata:

```bash
PR_NUMBER=$ARGUMENTS
PR_DATA=$(bash ${CLAUDE_PLUGIN_ROOT}/skills/code-review/scripts/fetch-pr-diff.sh $PR_NUMBER)
```

Extract key fields from the result:
- `owner`, `repo`: Repository context
- `title`, `body`: PR description
- `baseRef`, `headRef`: Branch names
- `changedFiles`: Array of changed file paths
- `diff`: Full unified diff

If the diff is large (more than 10 changed files), warn the user that the review may consume a significant portion of Pro plan token limits and ask whether to proceed. This threshold is based on typical token usage patterns where reviewing more than 10 files in a single session can consume a substantial portion of daily limits.

### Step 2: Dispatch Reviewer Agents

Launch all 8 reviewer agents in parallel using the Task tool. Use agent-specific subagent types (e.g., `github-devflow:logic-reviewer`). Each agent runs in its own isolated context with its system prompt, model, and tools automatically applied from the agent definition.

For each agent, provide a prompt containing the PR context:

**Prompt template for each agent:**

```
## PR Information
- Repository: {owner}/{repo}
- PR #{pr_number}: {title}
- Base: {baseRef} → Head: {headRef}
- Changed files: {changedFiles}

## Diff
{diff}

Review the changes and output your findings as JSON in the specified format.
```

**Important:** Launch ALL agents in a single message using multiple Task tool calls so they run in parallel. Use the following subagent types:
- `github-devflow:logic-reviewer`
- `github-devflow:design-reviewer`
- `github-devflow:security-reviewer`
- `github-devflow:performance-reviewer`
- `github-devflow:convention-reviewer`
- `github-devflow:git-history-reviewer`
- `github-devflow:pr-history-reviewer`
- `github-devflow:docs-reviewer`

The model for each agent is automatically determined from the agent's frontmatter (see the Review Perspectives table above for reference).

### Step 3: Collect and Aggregate Results

After all agents complete:

1. Parse JSON findings from each agent's response
2. Merge all findings into a single array
3. Deduplicate: if multiple agents flag the same file+line, combine their comments into one (noting each perspective)
4. Sort findings by file path, then line number

### Step 4: Generate Review Summary

Create a review summary body (markdown) that includes:

```markdown
## Multi-Perspective Code Review

This review was generated by analyzing PR #{pr_number} from 8 perspectives.

### Summary

| Perspective | Findings |
|-------------|----------|
| Logic & Correctness | X issues |
| Design & Maintainability | X issues |
| Security | X issues |
| Performance | X issues |
| Convention Compliance | X issues |
| Git History Context | X issues |
| PR History Context | X issues |
| Documentation | X issues |
| **Total** | **X issues** |

### Key Findings

[List the most important findings across all perspectives, grouped by severity (error > warning > info)]
```

### Step 5: Post the Review

1. Create the output directory and write the review summary:
   ```bash
   mkdir -p /tmp/github-devflow:code-review/${REPO}/${PR_NUMBER}
   # Write review body to /tmp/github-devflow:code-review/${REPO}/${PR_NUMBER}/review-body.md
   ```

2. Build the comments JSON array from aggregated findings:
   ```json
   [
     {
       "path": "src/main.py",
       "line": 42,
       "start_line": 40,
       "body": "**[Logic]** :warning: Description of issue..."
     }
   ]
   ```

   The `start_line` field is optional and enables multi-line comment ranges.

   Format each comment body with the perspective tag:
   - `**[Logic]** ` for logic-reviewer findings
   - `**[Design]** ` for design-reviewer findings
   - `**[Security]** ` for security-reviewer findings
   - `**[Performance]** ` for performance-reviewer findings
   - `**[Convention]** ` for convention-reviewer findings
   - `**[Git History]** ` for git-history-reviewer findings
   - `**[PR History]** ` for pr-history-reviewer findings
   - `**[Docs]** ` for docs-reviewer findings

   Prefix each comment with a severity emoji:
   - `:rotating_light:` for error
   - `:warning:` for warning
   - `:information_source:` for info

3. Write comments JSON to `/tmp/github-devflow:code-review/${REPO}/${PR_NUMBER}/review-comments.json`

4. Post the review:
   ```bash
   bash ${CLAUDE_PLUGIN_ROOT}/skills/code-review/scripts/post-review.sh $PR_NUMBER /tmp/github-devflow:code-review/${REPO}/${PR_NUMBER}/review-body.md /tmp/github-devflow:code-review/${REPO}/${PR_NUMBER}/review-comments.json
   ```

   Note: File paths must be within `/tmp/github-devflow:code-review/` for security validation.

### Step 6: Report Results

After posting, display a summary to the user:
- Total findings by perspective
- Total findings by severity
- Link to the posted review on GitHub

## Important Guidelines

### No Code Changes

**This skill must NOT modify any repository files.** Only analyze and post review comments:
- Do NOT use Write or Edit tools on repository files
- Do NOT create or modify any source files
- The Write tool is permitted ONLY for creating temp files under `/tmp/` for the review posting process

### Agent Output Parsing

Each agent returns a JSON object. Parse it carefully:
- If an agent fails or returns invalid JSON, skip its findings and note the failure in the summary
- If an agent returns empty findings, include it in the summary with 0 count

### Error Handling

- If `gh` CLI is not authenticated, inform the user to run `gh auth login`
- If the PR number is invalid, report the error clearly
- If posting the review fails, display the findings to the user in the terminal as fallback
- If individual agents fail, continue with the remaining agents' findings

### Rate Limiting

The git-history and pr-history agents make GitHub API calls. If rate limiting occurs, those agents will return partial or empty results. This is acceptable - note it in the summary.