PR review

Slice the diff; for each slice, one agent maps the catalog onto its added lines and reviews every concern it mapped; a separate skeptic validates every finding. The report is compiled mechanically from validated findings only. Every agent runs on the model of the session that invoked the skill. It launches a multi-agent run, so it runs only when the user invokes it.

Modes

• Review (default): the current branch against its base, or the named base branch or pull request.
• Mine (argument mine): build or refresh the project's concern catalog, per references/mining.md.

Inputs

• Settings first: Read .claude/shipyard/pr-review.md in the project root, if it exists, before anything else. It sets the base branch, review paths, security-sensitive paths, slice size, agent cap, findings cap, and CI-enforced rules with their suppression markers; shape in references/overlay-example.md.
• The catalog: every references/catalog-*.md (format in references/catalog.md) plus the project's .claude/shipyard/pr-review/concerns.md, which wins on id collisions.
• The diff, scoped once by scope.sh in this skill's folder and shared with every agent.

Pipeline

scope.sh ──> full.diff + diff.txt ("path:line: code", added lines only)
   │         slices: one if ≤ 10 files and ≤ 400 added lines; else ~400 lines each,
   ▼         by top-level directory, security paths alone, at most 6 (slices grow past it)
1 Map and review   concern-reviewer per slice, in parallel, whole catalog each:
   │               MAP concerns to its lines, then REVIEW each: finding or cleared
   ▼
check (no model)   drop findings whose evidence_line isn't at location; flag unreviewed ids
   ▼
2 Validate         review-verifier, one agent over every slice's findings:
   │               confirmed | false-positive | pre-existing | duplicate
   ▼
report from confirmed findings only: Bugs / Issues / Nits / Summary + coverage

Contracts, schemas, the slicing rule, and the report template: references/stages.md. The runnable script: references/workflow.js.

Rules

• Evidence line is mandatory. Every finding cites location and evidence_line verbatim from diff.txt; the mechanical check drops any whose line isn't there.
• Added lines only. Pre-existing defects are tagged and dropped, not reported.
• Severity: bug wrong behavior, data loss, or a security hole; issue a design defect a reviewer would block on; nit a minor preference with a reason. Mark design-level findings as possibly intentional.
• Findings cap from settings (default 10), highest severity first; say how many were cut.
• Don't re-flag what CI enforces, except an added line that suppresses a rule.
• Read-only end to end: no agent edits files or commits. Posting findings as PR comments is a separate step and a HUMAN TRIGGER: only on the user's approval.
• The coverage line reports what ran: counts from agent outputs and the check, n/a for any not computed, never an estimate; unreviewed concerns are listed, never hidden. The verdict is advisory.

Steps (review mode)

- [ ] 1 Read settings and resolve the base
- [ ] 2 Scope the diff
- [ ] 3 Run the two stages
- [ ] 4 Print the report
- [ ] 5 Offer rejected findings on request

1. Read settings and resolve the base: the settings' base branch, else the default branch; for a pull request, fetch its head into a worktree.
2. Scope the diff: bash <skill>/scope.sh <worktree> <base> <scratch> [review paths, :!skips], or --diff <file> when you were handed a diff. It prints files=N added=M; on added=0 report "No changes to review." and stop. Without a shell, build diff.txt from the diff yourself.
3. Run the two stages. With a workflow runner, run references/workflow.js with args worktree, base, scratch, skillDir, diff (the contents of diff.txt), title, focus (plus cap, ciRules, securityPaths, sliceLines, maxAgents from settings) and print its report verbatim. Without one, follow "Running without a workflow runner" in references/stages.md: concern-reviewer per slice (namespaced, e.g. shipyard-delivery:concern-reviewer) in parallel, the check, then review-verifier, each a direct child of this session.
4. Print the report: Bugs, Issues, Nits (each says none when empty, never omitted), then the Summary with the verdict and the coverage line.
5. Offer rejected findings on request: only if the user asks; they're the audit trail of what the check and validation killed.

Handoff

next: fixes go back to the implement stage; a clean review goes to the describe stage.