settled-reach/.claude/skills/pr-review/SKILL.md

name, description, user-invocable, allowed-tools

name	description	user-invocable	allowed-tools
pr-review	Review a branch diff with team-appropriate agents before merge. Use when the user says "review-pr", "review this PR", "review this branch", or invokes /pr-review. Spawns reviewers matched to the branch type (code, copy, visual, audio) in parallel. Reports approve/reject with inline comments.	true	Bash, Read, Grep, Glob, Task

PR Review Skill

Multi-agent review of a branch diff against main. Reviewer composition depends on the branch type. All reviewers must approve for a clean review.

Workflow

1. Determine the branch

If the user provided a branch name as argument, use it. Otherwise use the current branch (git branch --show-current). If on main, ask the user which branch to review.

To list open PRs on Gitea:

tea pr list --login schweitz --repo jpmschweitzer/settled-reach --state open --output simple

Fetch remote branches first:

git fetch --all

2. Determine reviewer team

Map the branch name to a reviewer set. Use the branch prefix (before any / or - suffix) to classify:

Branch type	Branches	Reviewers
code	server, client, ci, or unknown	Hoshe (code quality) + Tyre (architecture)
copy	copy	Hoshe (QA) + Paula (narrative depth) + Miri (world consistency)
visual	visual	Hoshe (QA) + Araminta (art direction)
audio	audio	Hoshe (QA) + Ozzie (player experience)

If the branch name doesn't match any known type, default to code reviewers.

3. Generate the diff and read source files

git log --oneline main..<branch>
git diff main...<branch> --stat

If the diff is empty, report "No changes to review" and stop.

Exclude generated/vendor files from the review diff. Common exclusions:

• Cargo.lock (auto-generated)
• client/addons/gdUnit4/ (vendor test framework)
• *.uid (Godot-generated)
• docs/backups/settledreach.db.backup (binary)

Three-dot diff with pathspec exclusions is unreliable. Instead, either:

1. Use git diff main...<branch> (full diff) and filter in the prompt, or
2. Read source files directly from the branch worktree (see below).

For large diffs (>1000 lines of source), provide source files rather than raw diff to reviewers — cleaner context, better reviews.

IMPORTANT — use worktree paths for ALL agents. This project uses git worktrees. Each team branch is checked out at:

/var/home/jeroenschweitzer/Projects/settled-reach/<branch>/

For example, the copy branch lives at:

/var/home/jeroenschweitzer/Projects/settled-reach/copy/content/dialogue/...

All reviewer agents (regardless of Bash access) should read source files from the worktree path using the Read tool. This is more reliable than git show origin/<branch>:<path> because:

• All agents have Read access (no Bash dependency)
• Files are always the actual branch checkout (no stale cache)
• No risk of accidentally reading from main's working directory

When constructing reviewer prompts, tell agents to read files from the worktree path. Example instruction for agents:

Read the changed files from the branch worktree. The branch is checked
out at: /var/home/jeroenschweitzer/Projects/settled-reach/<branch>/

For example, to read `content/dialogue/the-terminal/kael-davan.yaml`,
use: /var/home/jeroenschweitzer/Projects/settled-reach/<branch>/content/dialogue/the-terminal/kael-davan.yaml

Also tell agents to read relevant decisions/*.md files from the same worktree (they're identical to main, but using the worktree path keeps agents grounded in the correct directory).

4. Spawn reviewers in parallel

Use the Task tool to spawn all reviewers simultaneously in a single message.

Read references/reviewer-profiles.md for the full per-branch-type reviewer specifications (agent types, models, prompt focus areas). Match the branch type from step 2 to the corresponding section.

All reviewers: request structured verdict: APPROVE or REQUEST_CHANGES with file-specific comments.

5. Present results

Format the combined review as a table per reviewer. Include one section per reviewer that was spawned (2 for code/visual/audio, 3 for copy):

## Review: <branch> -> main  (type: code|copy|visual|audio)

### <Reviewer Name> (<Focus>): [APPROVE | REQUEST_CHANGES]
[Summary]
| # | File | Severity | Issue |
|---|------|----------|-------|
| 1 | path:line | critical/warning/suggestion | description |

### <Reviewer Name> (<Focus>): [APPROVE | REQUEST_CHANGES]
...

### Verdict: [APPROVED | CHANGES REQUESTED]

The overall verdict is APPROVED only if all reviewers approve.

Prompt template for reviewers

Use this structure when constructing the agent prompts (adapt as needed):

Review the following {branch_type} branch diff for merge into main.

Branch: {branch}
Branch type: {branch_type} (code|copy|visual|audio)
Commits:
{commit_log}

Diff stats:
{diff_stat}

[Source files or diff here — exclude vendor/generated code]

Your review focus: {focus_area}

Respond with:
1. Verdict: APPROVE or REQUEST_CHANGES
2. Summary: 2-3 sentence overall assessment
3. Comments: List of specific issues, each with:
   - File path and approximate location
   - Severity: critical / warning / suggestion
   - Description of the issue

Verdict rules:
- Any **critical** or **warning** issue → REQUEST_CHANGES
- Only **suggestion**-level issues (or none) → APPROVE
If no issues found, say APPROVE with a brief positive summary.

6. Posting results to Gitea

After presenting results to the user, post the review as a PR comment.

Note: tea pr reject does not work on your own PRs. Use tea comment instead.

IMPORTANT — tea comment hangs with inline heredocs and multi-line strings. Always use a two-step approach: write to a temp file first, then pass via $(cat):

# Step 1: Write review to .tmp/ using the Write tool (no permission prompt)
Write(file_path: "<repo_root>/.tmp/review-<branch>.md", content: "...review content...")

# Step 2: Post to Gitea (separate Bash call)
tea comment --login schweitz --repo jpmschweitzer/settled-reach <PR_NUMBER> "$(cat .tmp/review-<branch>.md)"

Use the Write tool for step 1 (avoids Bash permission prompts). The .tmp/ directory is gitignored and exists in the repo root for this purpose.

7. Merging approved PRs

tea pr merge fails (405) when branches have conflicts with main. Merge locally instead:

git fetch --all
git merge origin/<branch>        # resolve conflicts if any
git push origin main
tea pr close --login schweitz --repo jpmschweitzer/settled-reach <PR_NUMBER>

Gitea does not auto-close PRs when you push a local merge — always close manually with tea pr close after pushing.

Tips from practice

• Vendor code: Explicitly note vendor code in the prompt so reviewers focus on project code. Mention it as a separate architectural concern (should it be gitignored? submoduled?).
• Large PRs: For PRs touching many files, provide file-by-file source code rather than a single massive diff. Reviewers give better feedback.
• Multiple PRs: When reviewing several PRs, spawn all reviewers in one parallel batch (4 agents for 2 PRs). This is faster than sequential.
• Tyre reads decisions: Always tell Tyre to read the relevant decisions/*.md files — this grounds the review in project-specific architectural choices.
• Binary/DB files: Exclude binary files from the diff. Note them in the prompt as "also changed" if relevant.