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: git show origin/<branch>:<path>

For large diffs (>1000 lines of source), provide source files rather than raw diff to reviewers — cleaner context, better reviews. Read files with git show origin/<branch>:<path> and include them in the prompt.

IMPORTANT — agent tool access: Not all reviewer agents have Bash access. Agents that CAN read from branches themselves: Hoshe, Tyre, Araminta. Agents that CANNOT (no Bash tool): Paula, Miri, Ozzie, Gestalt, Gore, Nigel.

For agents without Bash, you MUST read the source files yourself (via git show origin/<branch>:<path>) and paste the file contents directly into the agent prompt. Do not tell these agents to read files — they can't. For very large PRs, read the key files (new/heavily modified) and include summaries or excerpts of minor changes. Also read and include the relevant decisions/*.md files these agents need for context.

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.