stack/packages/mosaic/framework/skills/pr-reviewer/SKILL.md

---
name: pr-reviewer
description: >
  Structured PR code review workflow. Use when asked to "review this PR",
  "code review", "review pull request", or "check this PR". Works with both
  GitHub and Gitea via platform-aware scripts. Fetches PR metadata and diff,
  analyzes against quality criteria, generates structured review files, and
  posts feedback only after explicit approval.
version: 2.0.0
category: code-review
triggers:
  - review pr
  - code review
  - review pull request
  - check pr
  - pr review
author: Adapted from SpillwaveSolutions/pr-reviewer-skill
license: MIT
tags:
  - code-review
  - pull-request
  - quality-assurance
  - gitea
  - github
---

# PR Reviewer

Structured, two-stage PR code review workflow. Nothing is posted until explicit user approval.

## Prerequisites

- `~/.config/mosaic/rails/git/` — Platform-aware git scripts must be available
- `python3` — For review file generation
- Current working directory must be inside the target git repository

## Workflow

### Stage 1: Collect and Analyze

#### 1. Gather PR Data

Run from inside the repo directory:

```bash
# Get PR metadata as JSON
~/.config/mosaic/rails/git/pr-metadata.sh -n <PR_NUMBER> -o /tmp/pr-review/metadata.json

# Get PR diff
~/.config/mosaic/rails/git/pr-diff.sh -n <PR_NUMBER> -o /tmp/pr-review/diff.patch

# View PR details (human-readable)
~/.config/mosaic/rails/git/pr-view.sh -n <PR_NUMBER>
```

#### 2. Analyze the Changes

With the diff and metadata collected, analyze the PR against these criteria:

| Category          | Key Questions                                               |
| ----------------- | ----------------------------------------------------------- |
| **Functionality** | Does the code solve the stated problem? Edge cases handled? |
| **Security**      | OWASP top 10? Secrets in code? Input validation?            |
| **Testing**       | Tests exist? Cover happy paths and edge cases?              |
| **Performance**   | Efficient algorithms? N+1 queries? Bundle size impact?      |
| **Readability**   | Clear naming? DRY? Consistent with codebase patterns?       |
| **Architecture**  | Follows project conventions? Proper separation of concerns? |
| **PR Quality**    | Focused scope? Clean commits? Clear description?            |

**Priority levels for findings:**

- **Blocker** — Must fix before merge
- **Important** — Should be addressed
- **Nit** — Nice to have, optional
- **Suggestion** — Consider for future
- **Question** — Clarification needed
- **Praise** — Good work worth calling out

#### 3. Generate Review Files

Create a findings JSON and run the generator:

```bash
python3 ~/.config/mosaic/skills/pr-reviewer/scripts/generate_review_files.py \
  /tmp/pr-review --findings /tmp/pr-review/findings.json
```

This creates:

- `pr/review.md` — Detailed analysis (internal use)
- `pr/human.md` — Clean version for posting (no emojis, concise)
- `pr/inline.md` — Proposed inline comments with code context

**Findings JSON schema:**

```json
{
  "summary": "Overall assessment of the PR",
  "metadata": {
    "repository": "owner/repo",
    "number": 123,
    "title": "PR title",
    "author": "username",
    "head_branch": "feature-branch",
    "base_branch": "main"
  },
  "blockers": [
    {
      "category": "Security",
      "issue": "Brief description",
      "file": "src/path/file.ts",
      "line": 45,
      "details": "Explanation of the problem",
      "fix": "Suggested solution",
      "code_snippet": "relevant code"
    }
  ],
  "important": [],
  "nits": [],
  "suggestions": ["Consider adding..."],
  "questions": ["Is this intended to..."],
  "praise": ["Excellent test coverage"],
  "inline_comments": [
    {
      "file": "src/path/file.ts",
      "line": 42,
      "comment": "Consider edge case",
      "code_snippet": "relevant code",
      "start_line": 40,
      "end_line": 44
    }
  ]
}
```

### Stage 2: Review and Post

#### 4. Present to User

Show the user:

1. The summary from `pr/review.md`
2. Count of blockers, important issues, nits
3. Overall recommendation (approve vs request changes)
4. Ask for approval before posting

**NOTHING is posted without explicit user consent.**

#### 5. Post the Review

After user approval:

```bash
# Option A: Approve
~/.config/mosaic/rails/git/pr-review.sh -n <PR_NUMBER> -a approve -c "$(cat /tmp/pr-review/pr/human.md)"

# Option B: Request changes
~/.config/mosaic/rails/git/pr-review.sh -n <PR_NUMBER> -a request-changes -c "$(cat /tmp/pr-review/pr/human.md)"

# Option C: Comment only (no verdict)
~/.config/mosaic/rails/git/pr-review.sh -n <PR_NUMBER> -a comment -c "$(cat /tmp/pr-review/pr/human.md)"
```

## Review Criteria Reference

See `references/review_criteria.md` for the complete checklist.

### Quick Checklist

- [ ] Code compiles and passes CI
- [ ] Tests cover new functionality
- [ ] No hardcoded secrets or credentials
- [ ] Error handling is appropriate
- [ ] No obvious performance issues (N+1, unnecessary re-renders, large bundles)
- [ ] Follows project CLAUDE.md and AGENTS.md conventions
- [ ] Commit messages follow project format
- [ ] PR description explains the "why"

## Best Practices

### Communication

- Frame feedback as suggestions, not demands
- Explain WHY something matters, not just WHAT is wrong
- Acknowledge good work — praise is part of review
- Prioritize: blockers first, nits last

### Efficiency

- Focus on what automated tools can't catch (logic, architecture, intent)
- Don't nitpick formatting — that's the linter's job
- For large PRs (>400 lines), suggest splitting
- Review in logical chunks (API layer, then UI, then tests)

### Platform Notes

- **Gitea**: Inline code comments are posted as regular PR comments with file/line references in the text
- **GitHub**: Full inline comment API available
- Both platforms support approve/reject/comment review actions via our scripts